Skills System

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

Getting Started

Core Features

Configuration

IDE Integration

Advanced

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

Export Skill

Import Skill

Skill Marketplace

Troubleshooting

Best Practices

Next Steps

Subagents

Session Commands

Extensions

Examples

​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

Subagents

Session Commands

Extensions

Examples

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