> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={null}
# 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`:

```markdown theme={null}
---
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, project-level Skills override user-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:** Project-level Skills override user-level Skills with the same name.

**Create the directory**:

```bash theme={null}
# 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:

```markdown theme={null}
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:

```markdown theme={null}
---
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**:

```bash theme={null}
# 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:

```bash theme={null}
# 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**:

```yaml theme={null}
# 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:

```markdown theme={null}
## 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**:

```bash theme={null}
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:

```yaml theme={null}
# 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**:

```bash theme={null}
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**:

```markdown theme={null}
---
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**:

````markdown theme={null}
---
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
````