Skills System - Qwen Code

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

# 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

Interactive
Command Line
Natural Language

# Use slash command
/skills code-review

# With additional context
/skills code-review Focus on the auth module

# 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)"

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?
...

Skill Structure

Skills are defined in SKILL.md files:

# 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

# 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

## 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:

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:

## 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:

# 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:

## 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:

code-review

Comprehensive code review covering:

Security vulnerabilities
Performance issues
Best practices
Code style
Test coverage

Usage: /skills code-review

debug-assistant

Systematic debugging workflow:

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

Usage: /skills debug-assistant

test-generator

Creates comprehensive tests:

Unit tests
Integration tests
Edge cases
Error scenarios
Mocking strategies

Usage: /skills test-generator

doc-writer

Generates documentation:

API docs
README files
Usage examples
Architecture diagrams
Inline comments

Usage: /skills doc-writer

refactor-guide

Safe refactoring workflow:

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

Usage: /skills refactor-guide

Skill Configuration

Per-Skill Settings

Configure individual skills:

// .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

// ~/.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:

Scanning configured locations
Looking for directories with SKILL.md files
Parsing the markdown for structure
Validating required sections
Caching for fast access

Refresh skill cache:

/memory refresh

Advanced Patterns

Multi-Phase Skills

# 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

# 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:

# Guided Refactoring

## Instructions

Ask: "What do you want to refactor?"
Ask: "What's the goal? (readability, performance, maintainability)"
Ask: "Any constraints?"
Analyze the code
Propose refactoring plan
Ask: "Approve this plan?"
Execute the refactoring
Run tests
Show summary of changes

Export Skill

# Package skill for sharing
tar -czf my-skill.tar.gz .qwen/skills/my-skill/

Import Skill

# Install shared skill
tar -xzf my-skill.tar.gz -C ~/.qwen/skills/

Skill Marketplace

Community skills:

# Install from marketplace (future feature)
qwen install-skill @community/react-expert
qwen install-skill @company/internal-standards

Troubleshooting

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

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

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

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)

Best Practices

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

Next Steps

Subagents

Combine skills with subagents for powerful workflows

Session Commands

Use /skills and other commands

Extensions

Create extensions that provide skills

Examples

Browse skill examples and templates

Documentation Index

​Overview

​Using Skills

​List Available Skills

​Invoke a Skill

​Skill Structure

​Advanced Skill with Configuration

​References

​Bundled Resources

​Skill Composition

​Conditional Logic

​Built-in Skills

​Skill Configuration

​Per-Skill Settings

​Global Skill Settings

​Skill Discovery

​Advanced Patterns

​Multi-Phase Skills

​Skills with Subagents

​Interactive Skills

​Sharing Skills

​Export Skill

​Import Skill

​Skill Marketplace

​Troubleshooting

​Best Practices

​Next Steps