Skills - Qoder CN

Skills package domain expertise into reusable capabilities in Qoder CN CLI. Each Skill contains a SKILL.md file that defines its description, instructions, and optional supporting files such as code, scripts, and templates. Core features:

Intelligent invocation: The model decides when to use a Skill based on user requests and Skill descriptions. Also supports command-based loading.
Modular design: Each Skill focuses on solving a specific type of task
Flexible extension: Supports both user-level and project-level custom Skills

Quick Start

This example creates an API documentation Skill:

1. Create Skill Directory

Create a directory in the user-level Skills folder. User-level Skills apply to all projects. Project-level Skills in .qoder/skills/ are shared with your team.

# Create user-level Skills directory
mkdir -p ~/.qoder-cn/skills/api-doc-generator

2. Write SKILL.md

Each Skill requires a SKILL.md file with YAML metadata between --- markers. Include name and description, followed by Markdown instructions. Create ~/.qoder-cn/skills/api-doc-generator/SKILL.md:

---
name: api-doc-generator
description: Generate comprehensive API documentation from code. Use when creating API docs, documenting endpoints, or generating OpenAPI specs.
---

# API Documentation Generator

When generating API documentation:

1. Identify all API endpoints and routes
2. Document request/response formats
3. Include authentication requirements
4. Add example requests and responses
5. Generate OpenAPI/Swagger specification if needed

3. Verify Skill Loading

Skills load automatically in new sessions. Verify loading:

What Skills are available?

Or use the command to verify:

/skills

The conversation should display api-doc-generator and its description.

4. Test the Skill

Open an API route file and enter a request matching the Skill description:

Generate documentation for this API

Qoder CN CLI applies the api-doc-generator Skill and generates API documentation. If it doesn't trigger, rephrase your request with keywords from the description.

How It Works

Skills can be loaded via commands or automatically invoked by the model based on request content.

At startup, Qoder CN CLI loads each Skill's name and description to keep startup fast while enabling the model to match requests to Skills.
When a request matches a Skill description, the model requests to use that Skill, displays a confirmation prompt, then loads the full SKILL.md. Include keywords users commonly use in your descriptions.
The model follows the Skill instructions, loading referenced files or running scripts as needed.

Storage Locations

Storage location determines availability scope:

Location	Path	Scope	Use Case
User-level	`~/.qoder-cn/skills/{skill-name}/SKILL.md`	All projects for the current user	Personal workflows, experimental Skills, personal tools
Project-level	`.qoder/skills/{skill-name}/SKILL.md`	Current project only	Team workflows, project-specific knowledge, shared scripts

When names conflict, project-level Skills override user-level Skills.

Skills vs Commands

Key difference: Skills support both command loading and automatic triggering, while Commands require explicitly typing /command-name.

Feature	Skill	Command
Trigger method	Model auto-decides or type `/skill-name`	Type `/command-name`
Primary purpose	Domain expertise, complex workflows	Quick preset task execution
Storage location	`skills/` directory	`commands/` directory
Permission confirmation	Required	Not required

Internally, Skills convert to a special Command type and share the same execution mechanism.

Use Cases

Scenarios suited for Skills:

Complex professional tasks: Workflows requiring domain knowledge (code review, PDF processing, API design)
Standardized processes: Tasks executed in fixed steps (commit conventions, deployment workflows)
Team knowledge sharing: Packaging best practices for team use
Repetitive work: Frequently executed tasks requiring expert guidance

Scenarios suited for Commands:

Simple quick operations
Tasks that need explicit triggering
Tasks that don't require complex prompt guidance

Creating a Skill

Choose Storage Location

Type	Path	Scope
User-level	`~/.qoder-cn/skills/{skill-name}/SKILL.md`	All projects for the current user
Project-level	`.qoder/skills/{skill-name}/SKILL.md`	Current project only

Project-level Skills override user-level Skills with the same name.

Create directory:

# User-level
mkdir -p ~/.qoder-cn/skills/{skill-name}

# Project-level
mkdir -p .qoder/skills/{skill-name}

Organize Directory Structure

Directory structure example:

{skill-name}/
├── SKILL.md          # Required: main file
├── REFERENCE.md      # Optional: detailed reference docs
├── EXAMPLES.md       # Optional: usage examples
├── scripts/          # Optional: helper scripts
│   └── helper.py
└── templates/        # Optional: template files
    └── template.txt

Reference supporting files in SKILL.md:

For better usage, see [REFERENCE.md].
For examples, see [EXAMPLES.md].
Run the helper script: python scripts/helper.py input.txt

Writing SKILL.md

SKILL.md is the only required file. It contains YAML metadata and Markdown instructions:

---
name: skill-name
description: Brief description of Skill functionality, explaining when to use it
---

# Skill Name

## Instructions
Provide clear step-by-step guidance.

## Examples
Show specific usage examples.

Frontmatter fields:

Field	Required	Description	Constraints
`name`	Yes	Unique Skill identifier	Lowercase letters, numbers, and hyphens only, max 64 characters
`description`	Yes	Functional description; the model uses this to determine when to invoke the Skill	Max 1024 characters

The description determines when the model invokes the Skill. Include what it does and when to use it.

Using Skills

Automatic Triggering

Describe your needs. The model automatically selects the appropriate Skill:

Analyze the errors in this log file

The model invokes the log-analyzer Skill.

Manual Triggering

Type /skill-name to manually trigger:

/log-analyzer

Viewing Available Skills

View in CLI:

What Skills are available?

View in file system:

# List user-level Skills
ls ~/.qoder-cn/skills/

# List project-level Skills
ls .qoder/skills/

# View SKILL.md files
ls ~/.qoder-cn/skills/*/SKILL.md
ls .qoder/skills/*/SKILL.md

Updating and Deleting

Updating a Skill

Edit SKILL.md directly. Changes take effect on the next Qoder CN CLI restart.

Deleting a Skill

Delete the Skill directory:

# User-level
rm -rf ~/.qoder-cn/skills/{skill-name}

# Project-level
rm -rf .qoder/skills/{skill-name}

Deletion permanently removes all Skill files and cannot be undone.

Best Practices

Stay Focused

Each Skill should focus on one domain or task type. Recommended:

log-analyzer - Log analysis
security-auditor - Security auditing
database-migrator - Database migration

Not recommended:

coding-helper - Too broad in scope

Write Clear Descriptions

Include what the Skill does, when to use it, and trigger keywords in the description. Comparison:

# Not recommended: vague
description: Helps with logs

# Recommended: specific
description: Analyze log files to identify errors, patterns, and performance issues. Use when debugging logs, investigating errors, or monitoring application behavior.

Before sharing a Skill, ensure:

It triggers in expected scenarios
Instructions are clear
Common edge cases are covered

Document Version Changes

Add version history to SKILL.md:

## Version History
- v2.0.0 (2026-10-01): Breaking API changes
- v1.1.0 (2026-09-15): New features added
- v1.0.0 (2026-09-01): Initial release

Troubleshooting

Skill Not Triggering

Check file location:

ls ~/.qoder-cn/skills/*/SKILL.md
ls .qoder/skills/*/SKILL.md

Confirm SKILL.md exists at the expected path. Check YAML format: Verify the frontmatter has no syntax errors such as incorrect indentation or mismatched quotes. Check description specificity: Use specific descriptions:

# Recommended: clear purpose and trigger conditions
description: Analyze log files to identify errors, patterns, and performance issues. Use when debugging logs, investigating errors, or monitoring application behavior.

# Not recommended: vague
description: For logs

Skill Execution Errors

Check dependencies: The CLI installs dependencies automatically or requests permission. Check script permissions:

chmod +x .qoder/skills/my-skill/scripts/*.py

Multiple Skills Conflicting

Differentiate similar Skills by using distinct trigger words in their descriptions.

Skill Examples

Example 1: Simple Skill

Analyze log files and diagnose issues. Directory structure:

log-analyzer/
└── SKILL.md

SKILL.md:

---
name: log-analyzer
description: Analyze log files to identify errors, patterns, and performance issues. Use when debugging logs, investigating errors, or monitoring application behavior.
---

# Log Analyzer

## Instructions

1. Read the log file to understand its format
2. Identify and categorize issues:
   - Error patterns and stack traces
   - Warning messages
   - Performance bottlenecks
   - Unusual patterns or anomalies
3. Provide summary with:
   - Issue severity and frequency
   - Root cause analysis
   - Recommended solutions

## Analysis tips
- Focus on recent critical errors first
- Look for recurring patterns
- Check timestamp correlations across entries

Example 2: Multi-file Skill

Database migration and version management tool. Directory structure:

database-migrator/
├── SKILL.md
├── MIGRATION_GUIDE.md
├── ROLLBACK.md
└── scripts/
    ├── generate_migration.py
    ├── validate_schema.py
    └── backup_db.sh

SKILL.md:

---
name: database-migrator
description: Generate and manage database migrations, schema changes, and data transformations. Use when creating migrations, modifying database schema, or managing database versions. Requires sqlalchemy and alembic packages.
---

# Database Migrator

## Quick start

Generate a new migration:

```bash
python scripts/generate_migration.py --name add_user_table
```

For detailed migration patterns, see [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md).
For rollback strategies, see [ROLLBACK.md](ROLLBACK.md).

## Workflow

1. **Analyze changes**: Compare current schema with desired state
2. **Generate migration**: Create migration file with up/down operations
3. **Validate**: Run `python scripts/validate_schema.py` to check syntax
4. **Backup**: Execute `scripts/backup_db.sh` before applying
5. **Apply**: Run migration in staging environment first
6. **Verify**: Check data integrity after migration

## Requirements

Install required packages:

```bash
pip install sqlalchemy alembic psycopg2-binary
```

## Safety checks

- Always backup before migrations
- Test rollback procedures
- Validate data integrity after changes
- Use transactions for atomic operations

​Quick Start

​1. Create Skill Directory

​2. Write SKILL.md

​3. Verify Skill Loading

​4. Test the Skill

​How It Works

​Storage Locations

​Skills vs Commands

​Use Cases

​Creating a Skill

​Choose Storage Location

​Organize Directory Structure

​Writing SKILL.md

​Using Skills

​Automatic Triggering

​Manual Triggering

​Viewing Available Skills

​Updating and Deleting

​Updating a Skill

​Deleting a Skill

​Best Practices

​Stay Focused

​Write Clear Descriptions

​Test Before Sharing

​Document Version Changes

​Troubleshooting

​Skill Not Triggering

​Skill Execution Errors

​Multiple Skills Conflicting

​Skill Examples

​Example 1: Simple Skill

​Example 2: Multi-file Skill

Quick Start

1. Create Skill Directory

2. Write SKILL.md

3. Verify Skill Loading

4. Test the Skill

How It Works

Storage Locations

Skills vs Commands

Use Cases

Creating a Skill

Choose Storage Location

Organize Directory Structure

Writing SKILL.md

Using Skills

Automatic Triggering

Manual Triggering

Viewing Available Skills

Updating and Deleting

Updating a Skill

Deleting a Skill

Best Practices

Stay Focused

Write Clear Descriptions

Test Before Sharing

Document Version Changes

Troubleshooting

Skill Not Triggering

Skill Execution Errors

Multiple Skills Conflicting

Skill Examples

Example 1: Simple Skill

Example 2: Multi-file Skill