Skills

A Skill is a folder containing a SKILL.md that teaches Qoder CLI how to do something specific: reviewing PRs using your team’s standards, generating commit messages in your preferred format, or querying your company’s database schema. When you ask Qoder CLI something that matches a Skill’s purpose, Qoder CLI automatically applies it.

Key features:

• Intelligent invocation: The model autonomously decides when to use a Skill based on user requests and Skill descriptions
• 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 a Skill for generating API documentation.

1. Create the Skill directory

Create a directory in your user-level Skills folder. User-level Skills are available across all your projects. You can also create project-level Skills in .qoder/skills/ to share with your team.

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

2. Write SKILL.md

Every Skill needs a SKILL.md file, starting with YAML metadata between --- markers that must include name and description, followed by Markdown instructions.

Create ~/.qoder/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. Load and verify the Skill

New sessions load Skills at startup. If Qoder CLI is already running, use /skills reload to refresh the discovered Skills. Verify successful loading:

What Skills are available?

Or use the command:

/skills

The conversation should show api-doc-generator with its description.

4. Test the Skill

Open an API route file in your project and ask a question matching the Skill’s description:

Generate documentation for this API

Qoder CLI applies the api-doc-generator Skill and generates relevant API documentation. If not triggered, try rephrasing using keywords from the description.

How Skills Work

Skills can be loaded via command or automatically invoked by the model. The model decides which Skill to use based on request content—no explicit specification needed.

1. Discovery: At startup, Qoder CLI loads each Skill’s name and description, enabling fast startup while letting the model understand each Skill’s applicable scenarios.
2. Activation: When a request matches a Skill’s description, the model requests to use that Skill and loads the full SKILL.md. Some Skills can run without an extra confirmation; Skills that need additional capabilities may ask for approval. Write descriptions that include keywords users commonly use.
3. Execution: The model executes according to Skill instructions, loading referenced files or running scripts as needed.

Where Skills live

Storage location determines a Skill’s availability:

Location	Path	Scope	Use cases
User-level	~/.qoder/skills/{skill-name}/SKILL.md	All projects for 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, user-level Skills override project-level Skills.

Skills vs Commands

Core difference: Skills are triggered automatically based on your request, while Commands require you to type /command-name explicitly.

Feature	Skill	Command
Trigger method	Automatic (model-based) or manual (/skill-name)	Manual (/command-name)
Primary use	Domain expertise, complex workflows	Quick preset tasks
Storage	skills/ directory	commands/ directory
Permission	May require approval depending on the Skill	Not required

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

When to Use Skills

Use Skills for:

• Complex specialized tasks: Workflows requiring domain expertise (code review, PDF processing, API design)
• Standardized processes: Tasks following fixed steps (commit conventions, deployment flows)
• Team knowledge sharing: Package best practices for sharing
• Repetitive work: Frequently executed tasks requiring specialized guidance

Use Commands for:

• Simple, quick operations
• Tasks requiring explicit user triggering
• Tasks not needing complex prompt guidance

Create a Skill

Choose Storage Location

Location	Path	Applies to
User-level	~/.qoder/skills/{skill-name}/SKILL.md	All projects for current user
Project-level	.qoder/skills/{skill-name}/SKILL.md	Current project only

Tip: User-level Skills override project-level Skills with the same name.

Create the directory:

# User-level
mkdir -p ~/.qoder/skills/my-skill-name

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

Organize Directory Structure

Directory structure example:

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

Reference auxiliary files in SKILL.md for progressive disclosure:

For better usage,see [REFERENCE.md]. For examples, see [EXAMPLES.md].

Run the helper script:

python scripts/helper.py input.txt

Write SKILL.md

Create SKILL.md with YAML frontmatter and Markdown content:

---
name: skill-name
description: Brief description of functionality and when to use
---

# 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, hyphens only; max 64 chars
description	Yes	Functional description for model to determine when to use	Max 1024 chars

Important: The description field is critical for the model to discover when to use your Skill. Include what it does and when to use it. See “Best Practices” section for details.

Use Skills

Automatic Trigger

Describe your need directly, the model automatically determines whether to use a Skill:

Analyze the errors in this log file

The model recognizes and invokes the log-analyzer Skill.

Manual Trigger

Use /skill-name to trigger manually:

/log-analyzer

View Available Skills

In CLI:

What Skills are available?

Through file system:

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

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

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

Update and Delete

Update a Skill

Edit SKILL.md directly. New sessions load the updated Skill on startup. If Qoder CLI is already running, run /skills reload to refresh the discovered Skills.

Delete a Skill

Delete the Skill directory:

# User-level
rm -rf ~/.qoder/skills/my-skill

# Project-level
rm -rf .qoder/skills/my-skill

Warning: Deleting a Skill directory permanently removes all files with no recovery.

Best Practices

Keep Skills Focused

Each Skill should focus on one specific domain or task type.

Recommended:

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

Not recommended:

• coding-helper - Too broad

Write Clear Descriptions

The description should include: what the Skill does, when to use it, and key trigger words.

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.

Test Before Sharing

Before sharing, ensure:

• Skill 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
- v1.0.0 (2026-09-01): Initial release

Troubleshooting

Skill Not Triggering

Check file location:

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

Confirm SKILL.md exists with correct path.

Check YAML format:

View SKILL.md to verify frontmatter has no syntax errors (indentation, quote matching).

Check description specificity:

Use clear, 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 dependency availability:

The CLI automatically installs required dependencies when needed (or requests permission).

Check script permissions:

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

Multiple Skills Conflict

When the CLI confuses similar Skills, use different trigger terms in descriptions to distinguish them.

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: Use multiple files

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