Qoder Skills 使用指南

Skill是一个名为SKILL.md按照团队标准审查 PR按照您偏好的格式生成提交信息查询公司的数据库架构当您的请求与 Skill 的用途匹配时，Qoder CLI 会自动应用它。

yunianshu

2543人浏览 · 2026-01-22 09:56:25

yunianshu · 2026-01-22 09:56:25 发布

Qoder Skills 使用指南

来源：https://docs.qoder.com/cli/Skills
文档生成时间：2026-01-22

📋 什么是 Skills？

Skill 是一个名为 SKILL.md 的 Markdown 文件，用于教导 Qoder CLI 如何执行特定任务：

按照团队标准审查 PR
按照您偏好的格式生成提交信息
查询公司的数据库架构

当您的请求与 Skill 的用途匹配时，Qoder CLI 会自动应用它。

核心特性

智能调用：模型根据用户请求和 Skill 描述自主决定何时使用 Skill
模块化设计：每个 Skill 专注于解决特定类型的任务
灵活扩展：支持用户级和项目级自定义 Skills

🚀 快速开始

示例：创建一个 API 文档生成器

1. 创建 Skill 目录

在个人 Skills 文件夹中创建目录。个人 Skills 在所有项目中可用。您也可以在 .qoder/skills/ 中创建项目 Skills 与团队共享。

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

2. 编写 SKILL.md

每个 Skill 都需要一个 SKILL.md 文件，以 --- 标记之间的 YAML 元数据开头，必须包含 name 和 description，后跟 Markdown 指令。

创建 ~/.qoder/skills/api-doc-generator/SKILL.md：

---
name: api-doc-generator
description: 从代码生成全面的 API 文档。在创建 API 文档、记录端点或生成 OpenAPI 规范时使用。
---

# API 文档生成器

生成 API 文档时：
1. 识别所有 API 端点和路由
2. 记录请求/响应格式
3. 包括身份验证要求
4. 添加示例请求和响应
5. 如需要，生成 OpenAPI/Swagger 规范

3. 加载和验证 Skill

创建或修改后，Skills 在新会话中自动加载。验证成功加载：

What Skills are available?

或使用命令查看（会显示 api-doc-generator 及其描述）

4. 测试 Skill

在项目中打开 API 路由文件并提出与 Skill 描述匹配的问题：

Generate documentation for this API

Qoder CLI 将应用 api-doc-generator Skill 并生成相关的 API 文档。如果未触发，尝试使用描述中的关键词重新表述。

🔄 Skills 工作原理

Skills 可以通过命令加载或由模型自动调用。模型根据请求内容决定使用哪个 Skill——无需明确指定。

工作流程

发现：启动时，Qoder CLI 加载每个 Skill 的名称和描述，实现快速启动，同时让模型了解每个 Skill 的适用场景
激活：当请求与 Skill 的描述匹配时，模型请求使用该 Skill。显示确认提示后，它加载完整的 SKILL.md。编写描述时包含用户常用的关键词
执行：模型按照 Skill 指令执行，根据需要加载引用的文件或运行脚本

Skills 存储位置

存储位置决定了 Skill 的可用性：

位置	路径	作用域	使用场景
个人	`~/.qoder/skills/{skill-name}/SKILL.md`	当前用户的所有项目	个人工作流、实验性 Skills、个人工具
项目	`.qoder/skills/{skill-name}/SKILL.md`	仅当前项目	团队工作流、项目特定知识、共享脚本

注意：当名称冲突时，项目 Skills 覆盖个人 Skills。

🔍 Skills vs Commands

核心区别

Skills 根据您的请求自动触发，而 Commands 需要您明确输入 /command-name。

特性	Skill	Command
触发方式	自动（基于模型）或手动（`/skill-name`）	手动（`/command-name`）
主要用途	领域专业知识、复杂工作流	快速预设任务
存储位置	`skills/` 目录	`commands/` 目录
权限要求	需要	不需要

注意：内部来说，Skills 会转换为特殊的 Command 类型并共享相同的执行机制。

🎯 何时使用 Skills

✅ 使用 Skills 适用于：

复杂专业任务：需要领域专业知识的工作流（代码审查、PDF 处理、API 设计）
标准化流程：遵循固定步骤的任务（提交约定、部署流程）
团队知识共享：打包最佳实践用于共享
重复性工作：需要专业指导的频繁执行任务

✅ 使用 Commands 适用于：

简单、快速的操作
需要明确用户触发的任务
不需要复杂提示指导的任务

📁 创建 Skill

1. 选择存储位置

位置	路径	适用于
个人	`~/.qoder/skills/{skill-name}/SKILL.md`	当前用户的所有项目
项目	`.qoder/skills/{skill-name}/SKILL.md`	仅当前项目

提示：项目 Skills 覆盖同名的个人 Skills。

创建目录：

# 用户级
mkdir -p ~/.qoder/skills/my-skill-name

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

2. 组织目录结构

目录结构示例：

{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

3. 编写 SKILL.md

创建包含 YAML frontmatter 和 Markdown 内容的 SKILL.md：

---
name: skill-name
description: 功能简述以及何时使用
---

# Skill Name

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

## Examples
展示具体使用示例。

Frontmatter 字段：

字段	必需	描述	约束
`name`	是	唯一的 Skill 标识符	仅小写字母、数字、连字符；最多 64 字符
`description`	是	功能描述，用于模型确定何时使用	最多 1024 字符

重要提示：description 字段对于模型发现何时使用您的 Skill 至关重要。包括它做什么以及何时使用它。请参阅"最佳实践"部分。

💡 使用 Skills

自动触发

直接描述您的需求，模型会自动确定是否使用 Skill：

Analyze the errors in this log file

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

手动触发

使用 /skill-name 手动触发：

/log-analyzer

查看可用 Skills

在 CLI 中：

What Skills are available?

通过文件系统：

# 列出用户级 Skills
ls ~/.qoder/skills/

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

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

✏️ 更新和删除

更新 Skill

直接编辑 SKILL.md。更改将在您下次启动 Qoder CLI 时生效。如果 CLI 已在运行，请重新启动以加载更新。

删除 Skill

删除 Skill 目录：

# 用户级
rm -rf ~/.qoder/skills/my-skill

# 项目级
rm -rf .qoder/skills/my-skill

警告：删除 Skill 目录将永久删除所有文件，无法恢复。

🌟 最佳实践

1. 保持 Skills 专注

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

2. 编写清晰的描述

description 应包括：Skill 做什么、何时使用它、关键触发词。

对比：

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

# 推荐：具体
description: 分析日志文件以识别错误、模式和性能问题。在调试日志、调查错误或监控应用程序行为时使用。

3. 共享前测试

在共享之前，确保：

Skill 在预期场景中触发
指令清晰
常见边缘情况被覆盖

4. 记录版本变更

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

## Version History

- v2.0.0 (2026-10-01): 破坏性 API 更改
- v1.1.0 (2026-09-15): 新功能
- v1.0.0 (2026-09-01): 初始发布

🛠️ 故障排除

Skill 未触发

检查文件位置：

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

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

检查 YAML 格式：

查看 SKILL.md 以验证 frontmatter 没有语法错误（缩进、引号匹配）。

检查描述具体性：

使用清晰、具体的描述：

# 推荐：明确目的和触发条件
description: 分析日志文件以识别错误、模式和性能问题。在调试日志、调查错误或监控应用程序行为时使用。

# 不推荐：模糊
description: For logs

Skill 执行错误

检查依赖可用性：

CLI 会在需要时自动安装所需的依赖（或请求权限）。

检查脚本权限：

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

多个 Skills 冲突

当 CLI 对相似的 Skills 感到困惑时，在描述中使用不同的触发词来区分它们。

📚 示例

示例 1：简单 Skill

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

目录结构：

log-analyzer/
└── SKILL.md

SKILL.md：

---
name: log-analyzer
description: 分析日志文件以识别错误、模式和性能问题。在调试日志、调查错误或监控应用程序行为时使用。
---

# Log Analyzer

## Instructions

1. 阅读日志文件以了解其格式
2. 识别和分类问题：
   - 错误模式和堆栈跟踪
   - 警告消息
   - 性能瓶颈
   - 异常模式或异常值
3. 提供摘要，包括：
   - 问题严重性和频率
   - 根本原因分析
   - 建议的解决方案

## Analysis tips

- 首先关注最近的严重错误
- 寻找重复模式
- 检查条目之间的时间戳关联

示例 2：使用多个文件

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

目录结构：

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: 生成和管理数据库迁移、架构更改和数据转换。在创建迁移、修改数据库架构或管理数据库版本时使用。需要 sqlalchemy 和 alembic 包。
---

# Database Migrator

## Quick start

生成新迁移：

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

有关详细的迁移模式，请参阅 MIGRATION_GUIDE.md。
有关回滚策略，请参阅 ROLLBACK.md。

Workflow

分析更改：比较当前架构与所需状态
生成迁移：创建包含 up/down 操作的迁移文件
验证：运行 python scripts/validate_schema.py 检查语法
备份：在应用之前执行 scripts/backup_db.sh
应用：首先在暂存环境中运行迁移
验证：迁移后检查数据完整性

Requirements

安装所需的包：

pip install sqlalchemy alembic psycopg2-binary

Safety checks

迁移前始终备份
测试回滚程序
更改后验证数据完整性
使用事务进行原子操作


---

## 📖 相关资源

- [Qoder 官方文档](https://docs.qoder.com)
- [CLI Commands 参考](https://docs.qoder.com/cli/Commands)

---

**文档版本**：1.0
**最后更新**：2026-01-22