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

# Skill Extensions

> Create specialized AI-invoked capabilities through skill extensions

# Creating Skill Extensions

Skills are specialized capabilities that the AI can automatically invoke when relevant to the user's request. Unlike commands (which users explicitly call), skills are model-invoked based on their descriptions and the current context.

## What are Skills?

Skills are:

* Capabilities the AI automatically uses when appropriate
* Defined in `SKILL.md` files with YAML frontmatter
* Discovered automatically by the AI
* Useful for adding domain-specific expertise
* Available via `/skills` command to view/manage

## Skill vs Command vs Agent

**Skill:**

* AI decides when to use it
* Single-purpose capability
* No conversation context
* Provides instructions/guidance

**Command:**

* User explicitly invokes with `/command`
* Can be multi-step workflow
* Immediate execution

**Agent:**

* User explicitly invokes
* Multi-turn conversation
* Complex, stateful interactions
* Has tool access

## Skill File Format

Skills are Markdown files with YAML frontmatter:

```markdown theme={null}
---
name: skill-name
description: Brief description of what this skill does and when to use it
license: MIT
---

# Skill Title

Detailed instructions for the AI on how to perform this skill.

## When to Use

Describe scenarios where this skill applies.

## How to Execute

Step-by-step guidance for the AI.

## Examples

Provide examples of inputs and expected outputs.

## Best Practices

Share guidelines and tips.
```

### Frontmatter Fields

**Required:**

* `name` - Unique identifier (lowercase, dashes)
* `description` - When and why to use this skill (crucial for AI discovery)

**Optional:**

* `license` - License information

### Description is Critical

The `description` field determines when the AI invokes your skill. Make it specific and context-rich:

```yaml theme={null}
# Good - Specific and descriptive
description: Analyzes code structure and provides insights about complexity, dependencies, and potential improvements. Use when user asks to analyze, review, or assess code quality.

# Bad - Too vague
description: Analyzes code
```

## Extension Structure

Place skill files in a `skills/` directory:

```
my-extension/
├── qwen-extension.json
└── skills/
    ├── code-analyzer/
    │   └── SKILL.md
    ├── test-generator/
    │   └── SKILL.md
    └── performance-profiler/
        └── SKILL.md
```

Each skill is in its own subdirectory with a `SKILL.md` file.

### Configure in Manifest

Update `qwen-extension.json`:

```json theme={null}
{
  "name": "my-extension",
  "version": "1.0.0",
  "skills": "skills"
}
```

The `skills` field specifies the directory (defaults to `"skills"` if not specified).

## Example: Synonyms Skill

From the built-in examples:

```markdown theme={null}
---
name: synonyms
description: Generate synonyms for words or phrases. Use this skill when the user needs alternative words with similar meanings, wants to expand vocabulary, or seeks varied expressions for writing.
license: Complete terms in LICENSE.txt
---

This skill helps generate synonyms and alternative expressions for given words or phrases. It provides contextually appropriate alternatives to enhance vocabulary and improve writing variety.

The user provides a word, phrase, or sentence where they need synonym suggestions. They may specify the context, tone, or formality level desired.

## Synonym Generation Guidelines

When generating synonyms, consider:

- **Context**: The specific domain or situation where the word will be used
- **Tone**: Formal, informal, neutral, academic, conversational, etc.
- **Nuance**: Subtle differences in meaning between similar words
- **Register**: Appropriate level of formality for the intended audience

## Output Format

For each input word or phrase, provide:

1. **Direct Synonyms**: Words with nearly identical meanings
2. **Related Alternatives**: Words with similar but slightly different connotations
3. **Context Examples**: Brief usage examples when helpful

## Best Practices

- Prioritize commonly used synonyms over obscure alternatives
- Note any subtle differences in meaning or usage
- Consider regional variations when relevant
- Indicate formality levels (formal/informal/neutral)
- Provide multiple options to give users choices

## Example

**Input**: "happy"

**Synonyms**:

- **Direct**: joyful, cheerful, delighted, pleased, content
- **Informal**: thrilled, stoked, over the moon
- **Formal**: elated, gratified, blissful
- **Subtle variations**:
  - _content_ - peaceful satisfaction
  - _ecstatic_ - intense, overwhelming happiness
  - _cheerful_ - outwardly expressing happiness
```

## Example: Code Analyzer Skill

```markdown theme={null}
---
name: code-analyzer
description: Analyzes code structure, complexity, dependencies, and provides insights about maintainability and potential improvements. Use when user asks to analyze, review, or assess code quality.
---

# Code Structure Analyzer

This skill provides comprehensive analysis of code structure, quality, and maintainability.

## When to Use

Activate this skill when the user:
- Asks to analyze code quality
- Wants to understand code complexity
- Needs insights about maintainability
- Requests dependency analysis
- Seeks improvement suggestions

## Analysis Approach

### 1. Structure Analysis

Examine:
- Module organization and boundaries
- Function/class sizes and responsibilities
- Code hierarchy and relationships
- Architectural patterns used

### 2. Complexity Assessment

Evaluate:
- Cyclomatic complexity
- Nesting depth
- Number of responsibilities per unit
- Cognitive load

### 3. Dependency Review

Analyze:
- External dependencies
- Internal coupling
- Dependency direction and layers
- Circular dependencies

### 4. Quality Indicators

Check for:
- Code duplication
- Naming clarity
- Comment quality and necessity
- Error handling patterns
- Test coverage indicators

## Output Format

Provide analysis in this structure:

### Summary
Brief overall assessment (2-3 sentences)

### Structure
- Organization: [assessment]
- Modularity: [assessment]
- Cohesion: [score/10]
- Coupling: [score/10]

### Complexity
- Overall complexity: [Low/Medium/High]
- Hot spots: [list complex areas]
- Refactoring opportunities: [suggestions]

### Dependencies
- Dependency count: [number]
- Coupling issues: [list]
- Suggestions: [improvements]

### Recommendations
1. [Priority 1 improvement]
2. [Priority 2 improvement]
3. [Priority 3 improvement]

### Code Examples
Show specific improvements with before/after code snippets.

## Best Practices

- Focus on actionable insights
- Prioritize issues by impact
- Provide specific code examples
- Suggest incremental improvements
- Consider project context and constraints
```

## Example: Performance Profiler Skill

````markdown theme={null}
---
name: performance-profiler
description: Identifies performance bottlenecks, analyzes algorithm complexity, and suggests optimizations. Use when user asks about performance, speed, optimization, or efficiency concerns.
---

# Performance Profiler

This skill helps identify and resolve performance issues in code.

## When to Use

Activate when the user:
- Reports slow performance
- Asks about optimization
- Wants to improve efficiency
- Questions algorithm complexity
- Needs scalability analysis

## Profiling Approach

### 1. Identify Bottlenecks

Look for:
- Nested loops (O(n²) or worse)
- Repeated computations
- Unnecessary data copies
- Blocking I/O operations
- Large memory allocations

### 2. Analyze Complexity

Determine:
- Time complexity (Big O notation)
- Space complexity
- Best/average/worst cases
- Scalability characteristics

### 3. Find Optimization Opportunities

Consider:
- Algorithm improvements
- Data structure changes
- Caching strategies
- Lazy evaluation
- Parallel processing
- Early termination

## Optimization Strategies

### Algorithm Level
- Replace O(n²) with O(n log n) or O(n)
- Use appropriate data structures
- Apply dynamic programming for overlapping subproblems
- Implement divide-and-conquer where applicable

### Code Level
- Cache computed values
- Avoid unnecessary operations
- Use efficient string operations
- Minimize object creation
- Batch operations

### I/O Level
- Batch database queries
- Use connection pooling
- Implement async operations
- Add appropriate indexes

## Output Format

### Performance Analysis

**Current Complexity**: O(?) time, O(?) space

**Bottlenecks Identified**:
1. [Location]: [Issue] - [Impact]
2. [Location]: [Issue] - [Impact]

**Optimization Opportunities**:

#### High Impact
1. [Suggestion]
   - Current: O(?)
   - Optimized: O(?)
   - Improvement: [X]x faster
   - Code example:
   ```language
   // Before
   [current code]
   
   // After
   [optimized code]
````

#### Medium Impact

\[Similar format]

#### Low Impact

\[Similar format]

**Trade-offs**:

* \[Optimization]: \[benefit] vs \[cost]

**Recommendations**:
Prioritized list of improvements to implement.

## Best Practices

* Measure before optimizing
* Focus on actual bottlenecks
* Consider maintainability vs performance
* Provide complexity analysis
* Show concrete improvements
* Mention trade-offs

````

## Example: API Design Skill

```markdown
---
name: api-designer
description: Designs RESTful APIs following best practices, including endpoint structure, HTTP methods, status codes, and documentation. Use when user is creating or reviewing API designs.
---

# API Design Specialist

This skill helps design well-structured, RESTful APIs.

## When to Use

Activate when the user:
- Designs a new API
- Reviews existing API structure
- Asks about REST best practices
- Needs endpoint recommendations
- Questions HTTP method usage

## API Design Principles

### 1. Resource-Oriented

- URLs represent resources (nouns), not actions
- Use HTTP methods for operations
- Logical hierarchy in paths

### 2. Consistent Naming

- Plural nouns for collections: `/users`, `/posts`
- Lowercase with hyphens: `/user-profiles`
- Predictable patterns throughout

### 3. Proper HTTP Methods

- `GET`: Retrieve resource(s)
- `POST`: Create new resource
- `PUT`: Replace entire resource
- `PATCH`: Partial update
- `DELETE`: Remove resource

### 4. Appropriate Status Codes

- `200`: Success
- `201`: Created
- `204`: No content (successful deletion)
- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `500`: Server error

## Design Process

### 1. Identify Resources

Determine:
- Main entities in the domain
- Resource relationships
- Collection vs individual resources

### 2. Define Endpoints

Structure:
````

GET    /resources           # List all
GET    /resources/{id}      # Get one
POST   /resources           # Create
PUT    /resources/{id}      # Replace
PATCH  /resources/{id}      # Update
DELETE /resources/{id}      # Delete

```

### 3. Handle Relationships

Nested resources:
```

GET /users/{id}/posts       # User's posts
GET /posts/{id}/comments    # Post's comments

```

### 4. Add Filtering/Pagination

```

GET /resources?page=2\&limit=20
GET /resources?status=active\&sort=-created\_at

````

## Output Format

### API Design

**Resource**: [Resource name]

**Endpoints**:

| Method | Path | Description | Request | Response |
|--------|------|-------------|---------|----------|
| GET | /path | Description | - | 200: {...} |
| POST | /path | Description | {...} | 201: {...} |

**Request Example**:
```json
POST /users
{
  "name": "John Doe",
  "email": "john@example.com"
}
````

**Response Example**:

```json theme={null}
201 Created
{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "created_at": "2024-01-01T00:00:00Z"
}
```

**Considerations**:

* \[Security concern]
* \[Performance consideration]
* \[Scalability note]

## Best Practices

* Version APIs: `/v1/resources`
* Use HTTPS only
* Implement rate limiting
* Provide clear error messages
* Document thoroughly
* Follow HATEOAS when appropriate
* Consider caching headers

````

## Best Practices

### 1. Focused Purpose

Each skill should have a single, clear purpose:

```yaml
# Good
name: test-generator
description: Generates unit tests for functions and classes

# Bad
name: code-helper
description: Helps with code
````

### 2. Rich Descriptions

Help the AI understand when to use your skill:

```yaml theme={null}
description: Analyzes database queries for performance issues, suggests indexes, and recommends query optimizations. Use when user asks about slow queries, database performance, or SQL optimization.
```

### 3. Clear Instructions

Provide step-by-step guidance:

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

1. **Understand Requirements**: Clarify what needs to be tested
2. **Identify Test Cases**: List normal, edge, and error cases
3. **Write Tests**: Create clear, focused tests
4. **Verify**: Ensure tests are runnable and pass
```

### 4. Include Examples

Show expected inputs and outputs:

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

**Input**: Function to validate email addresses

**Output**: Test suite covering:
- Valid email formats
- Invalid formats (missing @, etc.)
- Edge cases (empty string, special chars)
- Boundary conditions
```

### 5. Output Structure

Define consistent output format:

```markdown theme={null}
## Output Format

1. **Summary**: Brief overview
2. **Analysis**: Detailed findings
3. **Recommendations**: Actionable steps
4. **Examples**: Code snippets
```

## Skill Discovery

Users can view available skills:

```
/skills          # List all skills
/skills search   # Search skills
```

Extension skills appear in the skills list with their descriptions.

## Testing Skills

During development:

1. Link your extension: `qwen extensions link .`
2. Restart Qwen Code
3. Ask questions that should trigger your skill
4. Verify the AI uses the skill appropriately
5. Refine description and instructions based on results

## Multiple Skills

You can include multiple related skills:

```
coding-extension/
└── skills/
    ├── code-reviewer/
    │   └── SKILL.md
    ├── test-generator/
    │   └── SKILL.md
    ├── refactorer/
    │   └── SKILL.md
    └── documenter/
        └── SKILL.md
```

Each skill should remain focused on its specific capability.

## Next Steps

* [Creating Extensions](/extensions/creating-extensions) - Build a complete extension
* [Agents](/extensions/agents) - Create specialized AI assistants
* [Commands](/extensions/commands) - Add custom commands
* [Best Practices](/extensions/best-practices) - Extension development guidelines