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": "john@example.com"
}

Response Example:

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:

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

**Understand Requirements**: Clarify what needs to be tested
**Identify Test Cases**: List normal, edge, and error cases
**Write Tests**: Create clear, focused tests
**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

**Summary**: Brief overview
**Analysis**: Detailed findings
**Recommendations**: Actionable steps
**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:

Link your extension: qwen extensions link .
Restart Qwen Code
Ask questions that should trigger your skill
Verify the AI uses the skill appropriately
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

Documentation Index

​Creating Skill Extensions

​What are Skills?

​Skill vs Command vs Agent

​Skill File Format

​Frontmatter Fields

​Description is Critical

​Extension Structure

​Configure in Manifest

​Example: Synonyms Skill

​Example: Code Analyzer Skill

​Example: Performance Profiler Skill

​Medium Impact

​Low Impact

​Best Practices

​Best Practices

​2. Rich Descriptions

​3. Clear Instructions

​4. Include Examples

​5. Output Structure

​Skill Discovery

​Testing Skills

​Multiple Skills

​Next Steps

Creating Skill Extensions

What are Skills?

Skill vs Command vs Agent

Skill File Format

Frontmatter Fields

Description is Critical

Extension Structure

Configure in Manifest

Example: Synonyms Skill

Example: Code Analyzer Skill

Example: Performance Profiler Skill

Medium Impact

Low Impact

Best Practices

Best Practices

2. Rich Descriptions

3. Clear Instructions

4. Include Examples

5. Output Structure

Skill Discovery

Testing Skills

Multiple Skills

Next Steps