Qoder Skills 完全指南：从零开始，让 AI 按你的标准执行

一、理解 Skill 的本质：菜单与菜谱的比喻

二、Skill 是什么？结构与工作原理

your-skill-name/           ← 文件夹名用 kebab-case（小写+短横线）
├── SKILL.md               ← 必须有，且必须是这个大小写
├── scripts/               ← 可选：Python、Shell 等可执行脚本
│   ├── process_data.py
│   └── validate.sh
├── references/            ← 可选：按需加载的参考文档
│   ├── api-guide.md
│   └── examples/
└── assets/                ← 可选：模板、字体、图标等资源
    └── report-template.md

第一级：YAML Frontmatter（元数据头部）
  → 始终加载在 AI 的系统提示词中
  → 只包含 name 和 description
  → 作用：让 AI 知道"我有哪些技能、分别在什么时候用"
  → 类比：图书馆的目录卡片

第二级：SKILL.md 正文
  → 当 AI 判断当前任务与该 Skill 相关时，才加载完整正文
  → 包含具体执行步骤、示例、注意事项
  → 类比：从书架上取出那本书，深度阅读

第三级：scripts/ references/ assets/ 中的文件
  → 只在 Skill 执行过程中需要时才按需读取
  → 类比：书中引用的附录和参考资料

三、三个关键问题：Skill vs Slash Command vs MCP vs Rules

简单判断法则

需要调用外部系统（数据库、邮件、日历、Notion）？ → MCP
只是一条全局约束（语言、格式）？ → Rules  
一次性快捷操作，不需要复用？ → Slash Command
可复用的标准化工作流，需要团队共享？ → Skill ✅

实践结论：Slash Command 能做的，Skill 都能做（Skill 也可以通过 / 调用）。但 Skill 还能引用脚本、内嵌资源、模块化分发。对新用户来说，直接学 Skill 即可，无需纠结 Slash Command。

四、什么任务最适合写成 Skill？三大使用场景

根据 Anthropic 官方总结，Skill 最适合以下三类场景：

场景一：文档与资产创建（Document & Asset Creation）

适合人群：运营、产品、设计、所有人

核心特征：需要生成符合特定风格、规范或品牌标准的输出物

典型案例：

• 给产品制作宣传视频（Remotion Best Practice Skill）
• 生成高质量前端界面（frontend-design Skill）
• 按公司模板生成 Word/PPT/Excel 文档
• 制作符合设计规范的海报或社交媒体图文

为什么用 Skill：你不熟悉该领域，无法指导 AI 达到专业标准。Skill 携带了该领域的最佳实践，让 AI 直接按专家标准执行。

场景二：工作流自动化（Workflow Automation）

适合人群：开发、技术管理者、任何有重复性工作的人

核心特征：多步骤流程，期望每次输出结果一致

典型案例：

• 每次新增 API 后自动同步文档 + 兼容性检查 + 单元测试框架
• 代码提交前自动执行 Code Review 规范
• 按固定模板生成项目进展报告

为什么用 Skill：

• 重复动作脚本化 → 不遗漏任何步骤
• 不依赖 AI 每次"想起来"提醒 → 结果确定
• 将步骤固化到文件 → 减少 token 消耗，降低成本

场景三：MCP 能力增强（MCP Enhancement）

适合人群：已经连接了 MCP 的开发者、技术团队

核心特征：有了工具访问权限，但缺乏"怎么用好"的工作流知识

典型案例：

• 连接了 Linear MCP，但每次都要解释 Sprint 规划流程 → 写一个 Skill 固化这套流程
• 连接了 GitHub MCP，但代码审查没有标准 → 写一个 Skill 定义审查步骤

为什么用 Skill：

• MCP 解决"AI 能做什么"（工具访问）
• Skill 解决"AI 应该怎么做"（工作流知识）
• 两者结合，用户无需每次从头解释，AI 自动按最佳实践执行

五、安装你的第一个开源 Skill（5 分钟上手）

找到 Skill 的两个主要入口

• https://skills.sh — 当前最流行的开放 Skill 市场，含 Remotion（视频）、from-design（前端）等热门 Skill
• Qoder 官方 Skill 门户（即将上线，中英双语，按角色分类：开发 / 运营 / 产品 / AI 技术）

三种安装方式

方式 A：命令行安装（推荐，最快）

npx skills add <skill-name>

执行后，按交互提示：

1.选择目标 Agent → 选 Qoder

2.选择安装级别：

• Global（用户级）→ 安装到 ~/.qoder/skills/，适合个人长期使用
• Project（项目级）→ 安装到 <项目根>/.qoder/skills/，适合团队规范

3.选择 copy 模式，无需额外依赖

这个命令还有一个隐藏优势：它会为不同的 Agent 创建软链接，让多个工具共用同一份 Skill 文件，避免重复维护。

方式 B：手动放置文件

直接将 Skill 文件夹复制到以下目录：

# 用户级（全局生效）
~/.qoder/skills/

# 项目级（项目内生效，推荐团队规范）
<项目根目录>/.qoder/skills/

方式 C：在 Qoder Quest 模式中用内置 Skill 生成

Qoder Quest 模式内置了一个 create skill 元技能。直接对话：

帮我创建一个 Skill，用于 [描述你的需求]

AI 会引导你完成所有步骤，并自动放置到正确目录。

验证安装是否成功

在 Qoder 对话框输入 /，如果安装的 Skill 出现在联想列表中，说明安装成功。

或者直接在 Quest 模式中输入与该 Skill 匹配的任务，观察 AI 是否自动识别并调用。

⚠️ 注意：目前 Qoder Skills 不支持热更新，安装或修改 Skill 后，需要重启会话才能生效。

六、三大实战场景演示

场景 A：用 Skill 制作产品宣传视频（适合运营/产品）

背景：不懂视频制作，想为产品生成一个可下载的宣传视频文件。

无 Skill 时的困境：AI 给你三个不满意的方案——用 Python 库、纯 HTML 动画、或只生成素材，都不是你想要的。

操作步骤：

# 第一步：安装 Remotion Best Practice Skill
npx skills add remotion-best-practice
# 选择 Qoder，选择 Global，选择 copy 模式

# 第二步：在 Qoder Quest 模式中输入
帮我为 [产品名] 制作一个中文宣传视频，请先访问官网了解产品特性。

AI 执行流程：

1.自动识别并加载 Remotion Skill

2.访问官网，了解产品背景

3.按 Skill 的最佳实践搭建 Remotion 工程（自动处理 npm 环境）

4.生成分页视频脚本，渲染成视频文件

后续可继续提需求：更换配色匹配官网、替换为官网 Logo、增加 3D 效果……

场景 B：有 Skill 与无 Skill 的前端设计对比（适合所有人）

背景：用 AI 做了一个 Todo 网站，输出是典型的"AI 味"——蓝白配色、Inter 字体、毫无设计感。

无 Skill 时：你想改善但不知道怎么提需求，反复说"再好看一点"毫无效果。

安装 from-design Skill：

npx skills add from-design

同样的需求，有 Skill 后 AI 会：

1.首先确认设计方向（这是无 Skill 时根本不会问的环节）

2.选择独特字体搭配、非常规色彩方案、有格调的布局

3.输出具有审美一致性的完整设计

核心洞察：Skill 填补了你的"知识盲区"。你不知道怎么提设计需求，但 Skill 知道——它把设计领域的最佳实践打包进来，让 AI 按专家标准执行。

场景 C：规范化 Java 工程的 API 开发（适合开发/技术管理）

背景：团队规定新增 API 必须同步文档、做兼容性检查、写单元测试，但 AI 默认只写代码，经常遗漏。

Step 1：在 Quest 模式中生成 Skill

帮我创建一个 Skill，要求：
在创建、修改、删除 API 接口时，必须完成：
1. 同步更新 OpenAPI 格式的 API 文档
2. 检查新接口不破坏现有接口的兼容性
3. 生成对应的单元测试框架
4. 以 change log 格式记录本次变更

Step 2：强化 Skill——加入确定性脚本

在这个 Skill 中，添加一个 Python 脚本，
用于扫描项目内所有 API 接口，
检查是否每个接口都有对应的文档。
结果以报告形式输出。

AI 会在 scripts/check_api_docs.py 中生成脚本，并在 SKILL.md 中引用，以后直接本地运行，不消耗 AI token。

Step 3：放入项目目录，团队共享

git add .qoder/skills/
git commit -m "feat: add api-standard skill v1.0"
git push
# 团队成员 git pull 后立即生效

七、动手编写你自己的 Skill（含官方规范）

完整文件格式

---
name: your-skill-name
description: |
  [说明这个 Skill 做什么] + [说明什么时候使用它，含触发词]
  例如：当用户需要新增、修改或删除 API 接口时，
  或说到"接口文档"、"兼容性检查"、"单元测试"时，使用本 Skill。
license: MIT
metadata:
  author: 你的名字或团队
  version: 1.0.0
---

## 目标

[一句话描述这个 Skill 要实现什么]

## 执行步骤

### 第一步：[具体行动]

[清晰说明做什么，怎么做]

```bash
# 如需执行脚本，明确给出命令
python scripts/check_api_docs.py --project-id PROJECT_ID
期望输出：[描述成功时看到什么]

### 第二步：[具体行动]
[继续...]
示例
示例 1：[常见场景]
用户说："新增一个用户登录接口"
AI 执行步骤：
1. 创建接口代码
2. 在 OpenAPI 文档中添加对应条目
3. 检查是否与现有认证接口兼容
4. 生成 JUnit 测试框架
错误处理
错误：[常见错误信息]
● 原因：[为什么发生]
● 解决：[怎么修复]

参考资料
详见 references/api-guide.md

YAML Frontmatter 详解（最重要的部分）

Frontmatter 是 AI 决定"是否调用这个 Skill"的唯一依据。

---
name: api-standard-check     # 必须是 kebab-case，小写+短横线
description: |               # 必须同时包含"做什么"和"何时用"
  当开发者新增、修改或删除 API 接口时，自动执行本 Skill，
  完成 API 文档同步、向后兼容性检查和单元测试框架生成。
  触发词：接口文档、API 规范、兼容性、单元测试、接口变更。
---

可选字段（完整版）

---
name: api-standard-check
description: |
  [必填，1024字以内，无 XML 尖括号]
license: MIT
metadata:
  author: 栗子团队
  version: 1.0.0
  mcp-server: github        # 如果配合某个 MCP 使用，注明名称
  category: development
  tags: [api, documentation, testing]
  documentation: https://your-docs-url.com
---

禁止事项

# ❌ 禁止在 frontmatter 中使用 XML 尖括号
description: Use for <important> cases  # 错误！

# ❌ 禁止 name 中含 "claude" 或 "anthropic"（保留词）
name: claude-helper         # 错误！

# ❌ 禁止 name 有空格或大写
name: My Cool Skill         # 错误！
name: my-cool-skill         # ✅ 正确

写好 Description 的三个黄金原则

Description 是 Skill 的"触发器"，决定 AI 在什么时候调用它。

原则一：同时说明"做什么"和"什么时候用"

# ❌ 太模糊
description: 帮助处理项目。

# ❌ 只说做什么，没有触发条件
description: 创建复杂的多页面文档系统。

# ✅ 好的示例
description: |
  分析 Figma 设计文件并生成开发交付文档。
  当用户上传 .fig 文件、说到"设计规范"、
 "组件文档"或"设计转代码"时使用。

原则二：包含用户实际会说的话（触发词）

用户一般不会说专业术语，要预测他们的自然语言：

description: |
  管理 Linear 项目工作流，包括 Sprint 规划、任务创建和状态跟踪。
  当用户提到"冲刺"、"Linear 任务"、"项目计划"，
  或要求"创建工单"时触发。

原则三：控制长度，不超过 1024 字符

Frontmatter 会被加载到系统提示词中，过长会占用上下文。2-4 句话即可，核心信息优先。

正文写作的四个技巧

1.用第三人称描述步骤："当被触发时，AI 需要先……"而非"你要……"，便于阅读和修改

2.步骤编号化：每步只做一件事，AI 不会跳过或混淆顺序

3.关键验证前置：把最重要的检查放在最前面，用 ## 重要 或 CRITICAL: 标注

4.引用胜过嵌入：复杂文档放在 references/ 中，主文件只写引用路径，保持 SKILL.md 在 5000 词以内

八、五大进阶模式：让 Skill 处理复杂工作流

以下五种模式来自 Anthropic 官方总结的实践经验，适合需要处理更复杂场景的用户。

模式一：顺序工作流编排

适用：需要严格按顺序执行的多步流程

## 工作流：新客户接入

## 第一步：创建账户
调用 MCP 工具：`create_customer`
参数：姓名、邮箱、公司名

## 第二步：设置支付方式
调用 MCP 工具：`setup_payment`
等待：支付方式验证完成

## 第三步：创建订阅
调用 MCP 工具：`create_subscription`
依赖参数：来自第一步的 customer_id

## 第四步：发送欢迎邮件
调用 MCP 工具：`send_email`
模板：welcome_email_template

关键技巧：明确步骤依赖关系、在每步加验证、提供失败时的回滚指令。

模式二：跨 MCP 协调

适用：工作流跨越多个外部服务

## 设计转开发交付流程

### 阶段一：Figma 导出（Figma MCP）
1. 导出设计资产
2. 生成设计规范文档
3. 创建资产清单

### 阶段二：文件存储（Drive MCP）
1. 创建项目文件夹
2. 上传所有资产
3. 生成分享链接

### 阶段三：任务创建（Linear MCP）
1. 创建开发任务
2. 将资产链接附到任务
3. 分配给工程团队

### 阶段四：通知（Slack MCP）
1. 在 #engineering 频道发布交付摘要
2. 包含资产链接和任务引用

模式三：迭代优化循环

适用：需要多轮优化才能达到质量标准的输出

## 报告生成流程

### 初稿生成
1. 通过 MCP 获取数据
2. 生成第一版报告
3. 保存到临时文件

### 质量检查
1. 运行验证脚本：scripts/check_report.py
2. 检查项：缺失章节 / 格式不一致 / 数据错误

### 优化循环
1. 逐项修复检查出的问题
2. 重新生成受影响的章节
3. 再次验证
4. 重复直到通过质量标准

### 最终输出
1. 应用最终格式
2. 生成摘要
3. 保存正式版本

模式四：上下文感知的工具选择

适用：同一个目标，根据文件类型或场景选择不同工具

## 智能文件存储

## 决策树
1. 检查文件类型和大小
2. 选择最佳存储位置：
   - 大文件（>10MB）→ 云存储 MCP
   - 协作文档 → Notion/Google Docs MCP
   - 代码文件 → GitHub MCP
   - 临时文件 → 本地存储

## 执行存储
根据决策调用对应 MCP 工具，
并向用户说明选择该存储方式的原因。

模式五：领域专业知识内嵌

适用：需要将复杂的合规规则、行业知识内嵌到工作流中

## 支付处理合规流程

### 处理前（合规检查）
1. 获取交易详情（MCP）
2. 应用合规规则：
   - 检查制裁名单
   - 验证司法管辖权
   - 评估风险等级
3. 记录合规决策

### 执行处理
IF 合规通过：
  - 调用支付处理 MCP
  - 执行欺诈检测
  - 完成交易
ELSE：
  - 标记待人工审核
  - 创建合规案例

### 审计记录
- 记录所有合规检查过程
- 生成审计报告

九、测试与迭代：让 Skill 越来越准

三类测试，覆盖 Skill 生命周期

测试一：触发测试（最关键）

目标：确保 Skill 在正确的时机加载，不该加载时不加载。

✅ 应该触发的测试用例（至少 10 个）：
- "帮我新增一个用户登录接口"
- "这个 API 和现有接口会不会冲突"
- "帮我写接口文档"

❌ 不应该触发的测试用例：
- "帮我写一首诗"
- "旧金山的天气怎么样"
- "帮我做个 PPT"

快速诊断法：直接问 AI："你什么时候会用 [skill-name] 这个 Skill？" AI 会复述你的 description，根据复述结果判断是否需要调整描述。

测试二：功能测试

运行同一个请求 3-5 次，检查：

• 输出结果是否一致
• API 调用是否成功（0 错误为目标）
• 关键步骤是否都完成（无遗漏）

测试三：与无 Skill 基线对比

根据反馈信号迭代

信号：Skill 没有自动调用（触发不足）

• 问题：description 太模糊，或缺少用户实际会说的触发词
• 修复：在 description 中添加更多具体触发短语，包括技术术语和口语表达

信号：Skill 总是莫名被调用（过度触发）

• 问题：description 太宽泛
• 修复：加入负向说明，例如："Do NOT use for simple data queries (use data-viz skill instead)"

信号：Skill 被调用了但 AI 没有按步骤执行

• 问题：指令太冗长或模糊
• 修复：缩短正文，关键步骤前置，考虑用脚本替代语言描述（脚本是确定的，语言描述存在解读偏差）

动态优化：用自然语言修改 Skill

你刚才的输出中，[具体描述问题]。
请把这个改进固化到 [skill-name] 这个 Skill 文件中，
下次遇到同样情况时直接按新方式处理。

这是 Skill 区别于 Slash Command 的核心优势：Skill 是活文档，每次修正都可以沉淀，减少下次犯同样错误的概率。

十、团队协作与 Skill 治理

两级安装策略

Git 协作最佳实践

# 1. 将项目级 Skill 纳入版本控制
git add .qoder/skills/
git commit -m "feat: add api-standard skill v1.0"
git push

# 2. 团队成员拉取后立即生效，无需额外操作
git pull

# 3. 更新 Skill 时写清楚变更内容
git commit -m "fix(skill/api-standard): 增加对 DELETE 接口的兼容性检查"

Skill 版本管理建议

在 metadata 中维护版本号，重大变更在 references/CHANGELOG.md 中记录：

metadata:
  version: 1.2.0
  author: 栗子团队

对于 breaking change（会改变 AI 行为的变更），在 description 中注明，并在团队群里发布通知。

组织级 Skill 部署

如果你的公司使用 Claude 企业版，管理员可以在工作区级别统一部署 Skill，所有成员自动获得，并可集中管理版本更新（2025 年 12 月已上线此功能）。

十一、常见问题排查 FAQ

Q：Skill 上传失败，提示 "Could not find SKILL.md"

检查文件名是否严格为 SKILL.md（区分大小写）。skill.md、SKILL.MD 都不行。

ls -la your-skill-folder/   
# 应该看到 SKILL.md

Q：上传失败，提示 "Invalid frontmatter"

最常见的 YAML 格式错误：

# ❌ 缺少 --- 分隔符
name: my-skill
description: Does things

# ❌ 引号未关闭
description: "Does things

# ✅ 正确格式
---
name: my-skill
description: Does things
---

Q：AI 没有自动调用我装好的 Skill

两步排查：

1.输入 / 检查 Skill 是否出现在联想列表（确认安装成功）

2.询问 AI："你什么时候会用 [skill-name] 这个 Skill？" 根据回答判断 description 是否需要调整

临时解决：输入 /skill-name 手动调用，或在提示词中明确说"请使用 xxx Skill"。

Q：Skill 触发太频繁，影响不相关任务

在 description 中加入负向说明：

description: |
  用于 CSV 文件的高级数据分析（统计建模、回归分析、聚类）。
  不适用于简单数据查询（请使用 data-viz Skill）。

Q：Skill 加载了但 AI 没有按步骤执行

可能原因：

1.指令过于冗长 → 精简正文，关键步骤前置

2.语言描述模糊 → 用脚本替代语言描述（代码是确定的，语言存在解读偏差）

3.添加明确提醒：在关键步骤前加 CRITICAL: 或 ## 重要

Q：Skill 有多少数量限制？

产品层面没有数量限制。实际上限由上下文窗口决定，但由于 Skill 只加载 meta data，通常可以同时携带大量 Skill（建议不超过 20-50 个同时启用），远比 MCP 节省资源。

Q：一个 Skill 能不能调用另一个 Skill？

可以。由于所有 Skill 的 meta data 都在 Agent 的上下文中，一个 Skill 执行过程中可以自然地触发另一个。如有明确依赖，在 description 中注明（如"使用前请确保已安装 xxx Skill"）。

Q：Skill 里的 reference 文件越大越好吗？

不是。建议：

• SKILL.md 控制在 5000 词以内
• 大型文档放 references/ 并在正文中引用路径
• 核心步骤优先放在主文件，细节文档按需引用
• 可以引用外部网站链接，但要注意 token 消耗

Q：我用 Slash Command 习惯了，切到 Skill 有什么优势？

Slash Command 能做的，Skill 都能做（Skill 也可以 / 调用）。但 Skill 还支持：引用脚本文件、内嵌资源、模块化分发、Git 版本管理、跨团队共享。对于任何超过 3-4 行的重复性指令，Skill 都是更好的选择。

十二、最小闭环实践路径：现在就开始

不要等"完全准备好"再行动。按以下四步，30 分钟内完成你的第一个 Skill 实践：

第 1 步（5 分钟）：安装一个开源 Skill
→ 打开终端，运行：
    npx skills add from-design
→ 选择 Qoder，选择 Global，选择 copy 模式

第 2 步（5 分钟）：测试是否生效
→ 在 Qoder Quest 模式中，输入一个前端设计需求
→ 观察 AI 是否自动调用 from-design Skill
→ 如果没有，输入 "/from-design" 手动调用

第 3 步（10 分钟）：修改这个 Skill 的 description
→ 打开 ~/ .qoder/skills/from-design/SKILL.md
→ 在 description 中加一句符合你实际场景的触发词
→ 重启会话，再次测试

第 4 步（10 分钟）：为你的团队写第一个 Skill
→ 在项目目录下：
    mkdir -p .qoder/skills/my-first-skill
    touch .qoder/skills/my-first-skill/SKILL.md
→ 填写 name、description 和执行步骤
→ git commit 提交，通知团队成员拉取

别等完美，先让第一个 Skill 在你本地跑起来。你的 AI 工程化能力，就从这一次点击真正启程。

十三、附录：YAML Frontmatter 速查表 + 完整 Checklist

Frontmatter 完整速查

---
# ✅ 必填
name: skill-name-in-kebab-case
description: |
  [做什么] + [什么时候用，含触发词]
  不超过 1024 字符，不含 XML 尖括号

# 🔧 可选
license: MIT
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"
metadata:
  author: Your Name / Team
  version: 1.0.0
  mcp-server: server-name        # 配合哪个 MCP 使用
  category: productivity
  tags: [tag1, tag2]
  documentation: https://your-docs.com
  support: support@company.com
---

上线前完整 Checklist

开始之前

• [ ] 确定了 2-3 个具体使用场景
• [ ] 明确了需要用到哪些工具（内置 or MCP）
• [ ] 规划了文件夹结构

开发过程中

• [ ] 文件夹名是 kebab-case（无空格、无大写）
• [ ] 主文件名是 SKILL.md（大小写完全正确）
• [ ] YAML frontmatter 有 --- 开头和结尾
• [ ] name 字段：kebab-case，无空格，无大写
• [ ] description 包含"做什么"和"何时用"两部分
• [ ] description 不含 XML 尖括号（< >）
• [ ] 正文步骤清晰，每步只做一件事
• [ ] 关键步骤有错误处理说明
• [ ] 包含 1-2 个示例场景
• [ ] References 已清晰链接（不要内联大段文档）

测试阶段

• [ ] 用 10 个相关请求测试触发（目标：90% 自动触发）
• [ ] 用 5 个不相关请求测试（不应触发）
• [ ] 功能测试：重复运行同一任务，结果一致
• [ ] MCP 集成测试（如适用）：API 调用 0 失败
• [ ] 与无 Skill 基线对比，记录改善数据

发布之后

• [ ] 收集用户反馈
• [ ] 监控触发率（过多/过少）
• [ ] 定期迭代更新 description 和步骤
• [ ] 更新 metadata 中的 version 字段

资源链接

本文参考 Anthropic 官方《The Complete Guide to Building Skills for Claude》

关于作者

Heaven

阿里国际 AI 业务运营专家

• 10年+海外业务经验，熟悉海外流量生态
• 阿里国际AI产品增长负责人，从 0 到 1 操盘 Pic Copilot（出海 AI 电商设计产品，100w+ 电商用户）的GTM和用户增长——Product Hunt 冷启动、SEO / SEM、社媒营销，探索&跑通AI时代增长新范式

🔭 当前在做

正在深入探索 AI 海外内容营销系统的搭建与落地 （Claude ， QoderWork， Openclaw），通过内容+AI杠杆撬动业务流量增长 。非常欢迎同在这个方向上探索的朋友一起交流。