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:

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

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

{
  "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:

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

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

---
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/ # Get one POST /resources # Create PUT /resources/ # Replace PATCH /resources/ # Update DELETE /resources/ # Delete

### 3. Handle Relationships

Nested resources:

GET /users//posts # User’s posts GET /posts//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": "[e-mail]"
}

Response Example:

201 Created
{
  "id": 123,
  "name": "John Doe",
  "email": "[e-mail]",
  "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:

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:

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

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

## 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 - Build a complete extension
• Agents - Create specialized AI assistants
• Commands - Add custom commands
• Best Practices - Extension development guidelines