> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/QwenLM/qwen-code/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills System

> Reusable prompt templates and workflows for common tasks

## Overview

Skills are reusable prompt templates that encapsulate:

* **Instructions**: Specific guidance for the AI
* **Context**: Background information and resources
* **Tool configuration**: Which tools to enable/disable
* **Examples**: Sample inputs and expected outputs
* **Workflows**: Multi-step procedures

Think of skills as templates or playbooks that can be invoked by name.

## Using Skills

### List Available Skills

```bash theme={null}
# In interactive mode
/skills

# From command line
qwen --list-skills
```

Example output:

```
Available skills:

  code-review      Review code for quality and security
  debug-assistant  Help debug issues systematically
  doc-writer       Generate comprehensive documentation
  refactor-guide   Guide through safe refactoring
  test-generator   Create thorough test suites
  api-designer     Design REST APIs following best practices
```

### Invoke a Skill

<Tabs>
  <Tab title="Interactive">
    ```bash theme={null}
    # Use slash command
    /skills code-review

    # With additional context
    /skills code-review Focus on the auth module
    ```
  </Tab>

  <Tab title="Command Line">
    ```bash theme={null}
    # Invoke skill with prompt
    qwen --skill code-review --prompt "Review src/auth.ts"

    # Skill with additional files
    qwen --skill doc-writer --prompt "Document @include(src/api.ts)"
    ```
  </Tab>

  <Tab title="Natural Language">
    The AI can automatically recognize and use skills:

    ```
    > Help me debug why authentication is failing

    I'll use the debug-assistant skill to help systematically...

    [Skill: debug-assistant activated]

    Let's gather information:
    1. What error are you seeing?
    2. When did it start failing?
    ...
    ```
  </Tab>
</Tabs>

## Skill Structure

Skills are defined in `SKILL.md` files:

````markdown theme={null}
# Code Reviewer

A specialized skill for reviewing code quality, security, and best practices.

## Description

Reviews code systematically, checking for:
- Security vulnerabilities
- Performance issues  
- Code style and conventions
- Error handling
- Test coverage

## Instructions

When reviewing code:

1. Read the entire file or module first
2. Check for security issues (SQL injection, XSS, auth bugs)
3. Look for performance problems (N+1 queries, unnecessary loops)
4. Verify error handling is comprehensive
5. Check test coverage
6. Suggest specific improvements with examples

Be thorough but constructive. Prioritize critical issues.

## Tools

- `read`: Read source files
- `grep`: Search for patterns
- `glob`: Find files
- `web_fetch`: Look up best practices

## Examples

### Example 1: Security Review

User: Review this authentication code

Assistant: I'll review the authentication code for security issues...

[reviews code, finds issues]

Found 3 security concerns:
1. Password comparison uses == instead of constant-time compare
2. JWT secret is hardcoded
3. No rate limiting on login endpoint

[provides specific fixes]

## Configuration

```json
{
  "approvalMode": "plan",
  "temperature": 0.3
}
````

```

## Skill Locations

Skills can be stored at multiple levels:

<Tabs>
  <Tab title="User-Level">
    **Location:** `~/.qwen/skills/`
    
    Personal skills available in all projects:
    
```

\~/.qwen/skills/
├── code-review/
│   └── SKILL.md
├── debug-assistant/
│   └── SKILL.md
└── my-workflow/
└── SKILL.md

```
</Tab>
<Tab title="Project-Level">
**Location:** `.qwen/skills/`

Project-specific skills (shared with team):

```

.qwen/skills/
├── review-api/
│   └── SKILL.md
└── deploy-checklist/
└── SKILL.md

```

<Tip>
  Commit project skills to git so your team uses the same workflows.
</Tip>
</Tab>
<Tab title="Extension-Level">
**Location:** Extension packages

Skills provided by installed extensions:

```

node\_modules/@qwen-code/extension-react/skills/
├── react-component/
│   └── SKILL.md
└── react-hooks/
└── SKILL.md

````
</Tab>
</Tabs>

**Priority:** Project > User > Extension

## Creating Skills

### Basic Skill

Create `.qwen/skills/my-skill/SKILL.md`:

```markdown
# My Custom Skill

Brief description of what this skill does.

## Instructions

Detailed instructions for the AI:

1. First, do X
2. Then, check Y
3. Finally, output Z

Be specific and thorough.

## Tools

- `read`
- `write_file`
- `bash`
````

### Advanced Skill with Configuration

````markdown theme={null}
# API Generator

Generates REST API endpoints from specifications.

## Description

Creates complete API implementations including:
- Route handlers
- Request validation
- Error handling
- Tests
- Documentation

## Instructions

### Phase 1: Analysis

1. Read the API specification
2. Identify all endpoints
3. Determine request/response schemas
4. Check for existing patterns in the codebase

### Phase 2: Implementation

1. Create route files following project structure
2. Implement validation using project's validator
3. Add error handling middleware
4. Write integration tests
5. Generate OpenAPI documentation

### Phase 3: Verification

1. Run tests
2. Check that all endpoints are documented
3. Verify error responses are consistent

## Tools

- `read`: Read existing code and specs
- `grep`: Find patterns
- `write_file`: Create new files
- `edit`: Modify existing files
- `bash`: Run tests

## Examples

### Example 1: Simple CRUD API

**User:** Create CRUD endpoints for User resource

**Assistant:**
I'll create CRUD endpoints for the User resource...

[Creates routes, validation, tests]

Created:
- `src/routes/users.ts` - Route handlers
- `src/validation/users.ts` - Request schemas
- `tests/integration/users.test.ts` - Integration tests
- `docs/api/users.md` - API documentation

### Example 2: Complex API with Auth

**User:** Create authenticated endpoints for managing teams

**Assistant:**
I'll create team management endpoints with authentication...

[Creates routes with auth middleware, validation, tests]

## Configuration

```json
{
  "approvalMode": "auto-edit",
  "tools": {
    "bash": {
      "alwaysAllow": ["npm test", "npm run lint"]
    }
  },
  "temperature": 0.4
}
````

## References

* [REST API Best Practices](https://restfulapi.net/)
* [OpenAPI Specification](https://swagger.io/specification/)

````

## Skill Features

### Template Variables

Use variables in skill instructions:

```markdown
## Instructions

Review the {{file_path}} file for:
- {{focus_area}}
- {{additional_checks}}

Using {{coding_standard}} as the standard.
````

Invoke with variables:

```bash theme={null}
qwen --skill code-review \
  --var file_path="src/auth.ts" \
  --var focus_area="security" \
  --var coding_standard="our team guidelines"
```

### Bundled Resources

Include files with your skill:

```
my-skill/
  ├── SKILL.md
  ├── examples/
  │   ├── good-example.ts
  │   └── bad-example.ts
  ├── templates/
  │   └── api-template.ts
  └── references/
      └── best-practices.md
```

Reference in SKILL.md:

```markdown theme={null}
## Examples

Good pattern: @include(examples/good-example.ts)

Bad pattern: @include(examples/bad-example.ts)

## Templates

Use this template: @include(templates/api-template.ts)
```

### Skill Composition

Skills can invoke other skills:

```markdown theme={null}
# Comprehensive Review

## Instructions

1. First, run the `code-review` skill
2. Then, run the `test-coverage` skill  
3. Finally, run the `security-audit` skill
4. Synthesize all findings into a report
```

### Conditional Logic

Use conditional instructions:

```markdown theme={null}
## Instructions

@if {{language}} == "typescript"
  - Check for proper type annotations
  - Verify strict mode is enabled
@endif

@if {{framework}} == "react"
  - Check for proper hook usage
  - Verify no prop drilling
@endif
```

## Built-in Skills

Qwen Code includes several built-in skills:

<AccordionGroup>
  <Accordion title="code-review">
    Comprehensive code review covering:

    * Security vulnerabilities
    * Performance issues
    * Best practices
    * Code style
    * Test coverage

    **Usage:** `/skills code-review`
  </Accordion>

  <Accordion title="debug-assistant">
    Systematic debugging workflow:

    * Gather symptoms
    * Reproduce issue
    * Form hypothesis
    * Test hypothesis
    * Implement fix
    * Verify fix

    **Usage:** `/skills debug-assistant`
  </Accordion>

  <Accordion title="test-generator">
    Creates comprehensive tests:

    * Unit tests
    * Integration tests
    * Edge cases
    * Error scenarios
    * Mocking strategies

    **Usage:** `/skills test-generator`
  </Accordion>

  <Accordion title="doc-writer">
    Generates documentation:

    * API docs
    * README files
    * Usage examples
    * Architecture diagrams
    * Inline comments

    **Usage:** `/skills doc-writer`
  </Accordion>

  <Accordion title="refactor-guide">
    Safe refactoring workflow:

    * Add tests first
    * Identify code smells
    * Plan refactoring steps
    * Refactor incrementally
    * Verify behavior preserved

    **Usage:** `/skills refactor-guide`
  </Accordion>
</AccordionGroup>

## Skill Configuration

### Per-Skill Settings

Configure individual skills:

```json theme={null}
// .qwen/skills/my-skill/config.json
{
  "name": "my-skill",
  "description": "Custom skill for our project",
  "approvalMode": "auto-edit",
  "model": "gemini-2.5-pro",
  "temperature": 0.3,
  "maxTokens": 50000,
  "tools": {
    "enabled": ["read", "write_file", "edit", "bash"],
    "disabled": ["web_search"]
  },
  "context": {
    "includeFiles": [".qwen/coding-standards.md"],
    "includeMemory": true
  }
}
```

### Global Skill Settings

```json theme={null}
// ~/.qwen/settings.json
{
  "skills": {
    "enabled": true,
    "autoSuggest": true,
    "locations": [
      "~/.qwen/skills",
      ".qwen/skills",
      "./custom-skills"
    ],
    "defaults": {
      "approvalMode": "default",
      "temperature": 0.4
    }
  }
}
```

## Skill Discovery

Qwen Code finds skills by:

1. Scanning configured locations
2. Looking for directories with `SKILL.md` files
3. Parsing the markdown for structure
4. Validating required sections
5. Caching for fast access

Refresh skill cache:

```bash theme={null}
/memory refresh
```

## Advanced Patterns

### Multi-Phase Skills

```markdown theme={null}
# Complex Workflow

## Phase 1: Planning

[Instructions for planning phase]

**Deliverable:** Project plan in `plan.md`

## Phase 2: Implementation

[Instructions for implementation phase]

**Deliverable:** Working code in `src/`

## Phase 3: Testing

[Instructions for testing phase]

**Deliverable:** Test suite in `tests/`

## Phase 4: Documentation

[Instructions for documentation phase]

**Deliverable:** Docs in `docs/`
```

### Skills with Subagents

```markdown theme={null}
# Parallel Development

## Instructions

1. Analyze the requirements
2. Break into independent modules
3. For each module:
   - Delegate to a specialized subagent
   - Provide module-specific context
   - Set appropriate approval mode
4. Integrate results
5. Run integration tests

## Subagent Template

For each module, create a subagent with:
- Name: module name
- Task: implement the module
- Tools: read, write_file, edit, bash
- Approval: auto-edit
```

### Interactive Skills

Skills that ask questions:

```markdown theme={null}
# Guided Refactoring

## Instructions

1. Ask: "What do you want to refactor?"
2. Ask: "What's the goal? (readability, performance, maintainability)"
3. Ask: "Any constraints?"
4. Analyze the code
5. Propose refactoring plan
6. Ask: "Approve this plan?"
7. Execute the refactoring
8. Run tests
9. Show summary of changes
```

## Sharing Skills

### Export Skill

```bash theme={null}
# Package skill for sharing
tar -czf my-skill.tar.gz .qwen/skills/my-skill/
```

### Import Skill

```bash theme={null}
# Install shared skill
tar -xzf my-skill.tar.gz -C ~/.qwen/skills/
```

### Skill Marketplace

Community skills:

```bash theme={null}
# Install from marketplace (future feature)
qwen install-skill @community/react-expert
qwen install-skill @company/internal-standards
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Skill not found">
    **Problem:** `/skills my-skill` says skill not found.

    **Solutions:**

    * Check skill is in correct location
    * Verify `SKILL.md` filename (case-sensitive)
    * Refresh cache with `/memory refresh`
    * Check permissions on skill directory
  </Accordion>

  <Accordion title="Skill not following instructions">
    **Problem:** AI not following skill instructions precisely.

    **Solutions:**

    * Make instructions more specific and numbered
    * Add examples of desired behavior
    * Use imperatives ("Do X") not suggestions ("You might want to X")
    * Test with a more powerful model
  </Accordion>

  <Accordion title="Skill too verbose">
    **Problem:** Skill generates too much output.

    **Solutions:**

    * Add instruction: "Be concise"
    * Lower temperature in skill config
    * Set `maxTokens` limit
    * Use more specific prompts when invoking
  </Accordion>

  <Accordion title="Tool not available in skill">
    **Problem:** Skill tries to use a disabled tool.

    **Solutions:**

    * Add tool to skill's "Tools" section
    * Enable tool in skill config.json
    * Check global tool settings
    * Verify tool is installed (for MCP/extension tools)
  </Accordion>
</AccordionGroup>

## Best Practices

1. **Be specific**: Detailed instructions produce better results
2. **Include examples**: Show the AI what good output looks like
3. **Define deliverables**: Clearly state what the skill should produce
4. **Set approval modes**: Configure appropriate safety for the skill's actions
5. **Version control**: Keep project skills in git for team collaboration
6. **Test thoroughly**: Try skills with various inputs before relying on them
7. **Document variables**: List all required and optional variables
8. **Provide context**: Include relevant files and references
9. **Keep focused**: One skill = one purpose
10. **Iterate**: Refine skills based on usage and results

## Next Steps

<CardGroup cols={2}>
  <Card title="Subagents" icon="users" href="/features/subagents">
    Combine skills with subagents for powerful workflows
  </Card>

  <Card title="Session Commands" icon="terminal" href="/features/commands">
    Use /skills and other commands
  </Card>

  <Card title="Extensions" icon="puzzle" href="/developers/extensions">
    Create extensions that provide skills
  </Card>

  <Card title="Examples" icon="code" href="/examples/skills">
    Browse skill examples and templates
  </Card>
</CardGroup>