技能

1. 创建 Skill 目录

在用户级 Skills 文件夹中创建目录。用户级 Skills 适用于所有项目，也可在 .qodercn/skills/ 中创建项目级 Skills 与团队共享。

# 创建用户级 Skills 目录
mkdir -p ~/.qoder-cn/skills/api-doc-generator

2. 编写 SKILL.md

每个 Skill 需要一个 SKILL.md 文件，以 --- 标记之间的 YAML 元数据开头，必须包含 name 和 description，后跟 Markdown 指令。创建 ~/.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. 验证 Skill 加载

Skill 创建或修改后在新会话中会自动加载。输入如下内容，验证是否加载成功：

What Skills are available?

或者输入命令验证：

/skills

对话中应显示 api-doc-generator 及其描述。

4. 测试 Skill

打开项目中的 API 路由文件，输入与 Skill 描述匹配的问题：

为这个 API 生成文档

Qoder CN CLI 应用 api-doc-generator Skill 并生成相关 API 文档。若未触发，尝试使用 description 中的关键词重新描述需求。

存储位置

存储位置决定 Skill 的可用范围：

同名时，项目级 Skill 覆盖用户级 Skill。

Skill 与 Command 的区别

核心区别：Skill 支持命令加载和自动触发，Command 需显式输入 /command-name。

选择存储位置

创建目录：

# 用户级
mkdir -p ~/.qoder-cn/skills/{skill-name}

# 项目级
mkdir -p .qoder/skills/{skill-name}

组织目录结构

目录结构示例：

{skill-name}/
├── SKILL.md          # 必需：主文件
├── REFERENCE.md      # 可选：详细参考文档
├── EXAMPLES.md       # 可选：文档示例
├── scripts/          # 可选：辅助脚本
│   └── helper.py
└── templates/        # 可选：模板文件
    └── template.txt

在 SKILL.md 中引用辅助文件实现渐进式披露：

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

编写 SKILL.md

SKILL.md 是 Skill 中唯一必需的文件，包含 YAML 元数据和 Markdown 指令：

---
name: skill-name
description: Skill 功能简述，说明何时使用
---

# Skill Name

## Instructions
提供清晰的分步指导。

## Examples
展示具体用法。

Frontmatter 字段：

自动触发

直接描述需求，模型自动判断是否使用 Skill：

分析这个日志文件中的错误

模型识别并调用 log-analyzer Skill。

手动触发

输入 /skill-name 手动触发：

/log-analyzer

查看可用 Skill

CLI 中查看：

What Skills are available?

文件系统查看：

# 列出用户级 Skill
ls ~/.qoder-cn/skills/

# 列出项目级 Skill
ls .qoder/skills/

# 查看 SKILL.md 文件
ls ~/.qodercn/skills/*/SKILL.md
ls .qodercn/skills/*/SKILL.md

更新 Skill

直接编辑 SKILL.md，下次启动 Qoder CN CLI 时生效。CLI 运行中需重启以加载更新。

删除 Skill

删除 Skill 目录：

# 用户级
rm -rf ~/.qoder-cn/skills/{skill-name}

# 项目级
rm -rf .qoder/skills/{skill-name}

保持专注

每个 Skill 专注于一个领域或任务类型。

推荐：

• log-analyzer - 日志分析

• security-auditor - 安全审计

• database-migrator - 数据库迁移

不推荐：

• coding-helper - 功能过于宽泛

编写清晰的 description

description 应包含：Skill 功能、使用时机和触发关键词。

对比：

# 不推荐：模糊
description: Helps with logs

# 推荐：具体
description: Analyze log files to identify errors, patterns, and performance issues. Use when debugging logs, investigating errors, or monitoring application behavior.

共享前测试

共享 Skill 前确保：

• 预期场景下能触发

• 指令清晰

• 覆盖常见边界情况

记录版本变更

在 SKILL.md 中添加版本历史：

## 版本历史
- v2.0.0 (2026-10-01): API 重大变更
- v1.1.0 (2026-09-15): 新增功能
- v1.0.0 (2026-09-01): 首次发布

Skill 未触发

检查文件位置：

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

确认 SKILL.md 存在且路径正确。

检查 YAML 格式：查看 SKILL.md，验证 frontmatter 无语法错误（缩进、引号匹配）。

检查 description 具体性：使用清晰具体的描述：

# 推荐：明确用途和触发条件
description: Analyze log files to identify errors, patterns, and performance issues. Use when debugging logs, investigating errors, or monitoring application behavior.

# 不推荐：模糊
description: For logs

Skill 执行出错

检查依赖：CLI 在需要时自动安装依赖（或请求权限）。

检查脚本权限：

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

多个 Skill 冲突

Skill 相似导致混淆时，在 description 中使用不同触发词区分。

示例 1：简单 Skill

分析日志文件并诊断问题。

目录结构：

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

示例 2：多文件 Skill

数据库迁移与版本管理工具。

目录结构：

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