推荐语
掌握AI时代的"菜谱"技能，让AI精准执行你的需求，告别反复调教与低效沟通。
核心内容：
1. Skill的本质与价值：从菜单与菜谱的比喻理解AI执行标准
2. Skill的结构与工作原理：开放标准文件夹的组成与功能
3. 实践应用：如何构建Skill提升人机协同效能与项目交付质量
杨芳贤
53AI创始人/腾讯云(TVP)最具价值专家
在 AI 原生工作流加速普及的今天，掌握 Skill 已不再是开发者的专属能力，而是产品、运营、设计乃至技术管理者提升人机协同效能的核心职业素养。它直接决定你能否把模糊需求转化为稳定、可复用、可协作的 AI 执行单元，从而在项目交付中显著提升质量一致性、降低沟通成本、规避重复试错。想象你走进一家餐馆，直接对厨师说："帮我做一道红烧肉。"
结果——厨师按自己的理解自由发挥。你收到的可能是完全不合口味的东西。
这正是我们每天在用 AI 时遇到的问题。
你向 AI 传达了需求，AI 却按自己的理解执行，导致你不得不反复修正输出，持续"调教"——高成本、低确定性、难以复现。
Skill 就是 AI 世界里的菜谱（Recipe）。
当 AI 有了一份清晰的菜谱，它就知道：
这道菜的标准做法是什么
哪些步骤是必须的
用哪些食材、什么火候、什么顺序
你作为顾客（用户）只需点菜，AI（厨师）就能按菜谱稳定交付。
整个 AI 工具生态的类比映射
餐馆场景 | AI 工具 | 说明 |
菜谱 / 菜单 | Skill | 告诉 AI 怎么做、按什么标准做 |
厨师 | Agent / 模型 | 执行者 |
食材 + 专业厨具 | MCP | 连接外部服务，提供"食材" |
今天的固定套餐 | Slash Command（/指令） | 一次性快捷指令 |
厨房基本规则 | Rules | 全局约束，始终生效 |
副厨、帮厨 | Sub-agent | 专项协作角色 |
MCP 提供专业厨房——让 AI 能访问你的工具、数据和外部服务。
Skill 提供菜谱——告诉 AI 如何将这些工具用好、按什么工作流执行。两者结合，才能让用户无需每次从头解释，AI 也能稳定交付高质量结果。
Skill 是一个开放标准的文件夹，包含一套告诉 AI 如何处理特定任务或工作流的指令。它是目前最强大的 AI 定制方式之一：教 AI 一次，永久受益——不再需要在每次对话中重新解释你的偏好、流程和领域知识。
your-skill-name/ ← 文件夹名用 kebab-case（小写+短横线）├── SKILL.md ← 必须有，且必须是这个大小写├── scripts/ ← 可选：Python、Shell 等可执行脚本│ ├── process_data.py│ └── validate.sh├── references/ ← 可选：按需加载的参考文档│ ├── api-guide.md│ └── examples/└── assets/ ← 可选：模板、字体、图标等资源 └── report-template.md
⚠️ 三个命名硬规则：
三级渐进式披露机制（Progressive Disclosure）
这是 Skill 最核心的工作原理，决定了它既节省上下文，又能承载复杂知识：
第一级：YAML Frontmatter（元数据头部） → 始终加载在 AI 的系统提示词中 → 只包含 name 和 description → 作用：让 AI 知道"我有哪些技能、分别在什么时候用" → 类比：图书馆的目录卡片
第二级：SKILL.md 正文 → 当 AI 判断当前任务与该 Skill 相关时，才加载完整正文 → 包含具体执行步骤、示例、注意事项 → 类比：从书架上取出那本书，深度阅读
第三级：scripts/ references/ assets/ 中的文件 → 只在 Skill 执行过程中需要时才按需读取 → 类比：书中引用的附录和参考资料
这个机制的三大优势：
优势 | 说明 |
省上下文 | 大量 Skill 并存时，AI 只加载目录信息，不会撑爆上下文窗口 |
省推理成本 | 步骤清晰，AI 减少"想怎么做"的推理次数，降低 token 消耗 |
结果确定 | 固定步骤 + 可脚本化执行，输出稳定，关键细节不遗漏 |
Skill 是开放标准，在以下环境中完全兼容：
创建一次，所有平台通用。
三、三个关键问题：Skill vs Slash Command vs MCP vs Rules
维度 | Skill | Slash Command | MCP | Rules |
触发方式 | AI 自主判断 + 可主动 / 调用 | 用户主动输入 /xxx | 工具调用时自动触发 | 始终在上下文中生效 |
内容复杂度 | 高：多步骤、脚本、资源、引用文件 | 低：固定短提示词 | 中：工具接口定义 | 低：全局约束规则 |
上下文占用 | 极低（只加载 meta data） | 中（加载固定提示词） | 高（一次性加载所有工具定义） | 低（始终存在） |
可分发性 | ✅ 天然适合团队共享和生态传播 | ❌ 难以共享 | ✅ 通过服务端共享 | ❌ 通常个人配置 |
适合场景 | 重复性工作流、跨项目规范、领域最佳实践 | 一次性快捷动作 | 调用外部系统数据 | 全局行为约束 |
需要调用外部系统（数据库、邮件、日历、Notion）？ → MCP只是一条全局约束（语言、格式）？ → Rules 一次性快捷操作，不需要复用？ → Slash Command可复用的标准化工作流，需要团队共享？ → Skill ✅
💡 实践结论：Slash Command 能做的，Skill 都能做（Skill 也可以通过 / 调用）。但 Skill 还能引用脚本、内嵌资源、模块化分发。对新用户来说，直接学 Skill 即可，无需纠结 Slash Command。
根据 Anthropic 官方总结，Skill 最适合以下三类场景：
场景一：文档与资产创建（Document & Asset Creation）
适合人群：运营、产品、设计、所有人
核心特征：需要生成符合特定风格、规范或品牌标准的输出物
典型案例：
给产品制作宣传视频（Remotion Best Practice Skill）
生成高质量前端界面（frontend-design Skill）
按公司模板生成 Word/PPT/Excel 文档
制作符合设计规范的海报或社交媒体图文
为什么用 Skill：你不熟悉该领域，无法指导 AI 达到专业标准。Skill 携带了该领域的最佳实践，让 AI 直接按专家标准执行。
场景二：工作流自动化（Workflow Automation）
适合人群：开发、技术管理者、任何有重复性工作的人
核心特征：多步骤流程，期望每次输出结果一致
典型案例：
为什么用 Skill：
场景三：MCP 能力增强（MCP Enhancement）
适合人群：已经连接了 MCP 的开发者、技术团队
核心特征：有了工具访问权限，但缺乏"怎么用好"的工作流知识
典型案例：
为什么用 Skill：
五、安装你的第一个开源 Skill（5 分钟上手）
方式 A：命令行安装（推荐，最快）
npx skills add <skill-name>
执行后，按交互提示：
1.选择目标 Agent → 选 Qoder
2.选择安装级别：
3.选择 copy 模式，无需额外依赖
💡 这个命令还有一个隐藏优势：它会为不同的 Agent 创建软链接，让多个工具共用同一份 Skill 文件，避免重复维护。
方式 B：手动放置文件
直接将 Skill 文件夹复制到以下目录：
~/.qoder/skills/
<项目根目录>/.qoder/skills/
方式 C：在 Qoder Quest 模式中用内置 Skill 生成
Qoder Quest 模式内置了一个 create skill 元技能。直接对话：
AI 会引导你完成所有步骤，并自动放置到正确目录。
在 Qoder 对话框输入 /，如果安装的 Skill 出现在联想列表中，说明安装成功。
或者直接在 Quest 模式中输入与该 Skill 匹配的任务，观察 AI 是否自动识别并调用。
⚠️ 注意：目前 Qoder Skills 不支持热更新，安装或修改 Skill 后，需要重启会话才能生效。
场景 A：用 Skill 制作产品宣传视频（适合运营/产品）
背景：不懂视频制作，想为产品生成一个可下载的宣传视频文件。
无 Skill 时的困境：AI 给你三个不满意的方案——用 Python 库、纯 HTML 动画、或只生成素材，都不是你想要的。
操作步骤：
npx skills add remotion-best-practice
帮我为 [产品名] 制作一个中文宣传视频，请先访问官网了解产品特性。
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
---name: your-skill-namedescription: | [说明这个 Skill 做什么] + [说明什么时候使用它，含触发词] 例如：当用户需要新增、修改或删除 API 接口时， 或说到"接口文档"、"兼容性检查"、"单元测试"时，使用本 Skill。license: MITmetadata: author: 你的名字或团队 version: 1.0.0---
[一句话描述这个 Skill 要实现什么]
[清晰说明做什么，怎么做]
```bashpython scripts/check_api_docs.py --project-id PROJECT_ID期望输出：[描述成功时看到什么]
[继续...]示例示例 1：[常见场景]用户说："新增一个用户登录接口"AI 执行步骤：1. 创建接口代码2. 在 OpenAPI 文档中添加对应条目3. 检查是否与现有认证接口兼容4. 生成 JUnit 测试框架错误处理错误：[常见错误信息]● 原因：[为什么发生]● 解决：[怎么修复]
参考资料
---
### YAML Frontmatter 详解（最重要的部分）
Frontmatter 是 AI 决定"是否调用这个 Skill"的唯一依据。
**必填字段**
```yaml---name: api-standard-check # 必须是 kebab-case，小写+短横线description: | # 必须同时包含"做什么"和"何时用" 当开发者新增、修改或删除 API 接口时，自动执行本 Skill， 完成 API 文档同步、向后兼容性检查和单元测试框架生成。 触发词：接口文档、API 规范、兼容性、单元测试、接口变更。---
可选字段（完整版）
---name: api-standard-checkdescription: | [必填，1024字以内，无 XML 尖括号]license: MITmetadata: author: 栗子团队 version: 1.0.0 mcp-server: github # 如果配合某个 MCP 使用，注明名称 category: development tags: [api, documentation, testing] documentation: https://your-docs-url.com---
禁止事项
description: Use for <important> cases
name: claude-helper
name: My Cool Skill name: my-cool-skill
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 词以内
以下五种模式来自 Anthropic 官方总结的实践经验，适合需要处理更复杂场景的用户。
适用：需要严格按顺序执行的多步流程
#
#调用 MCP 工具：`create_customer`参数：姓名、邮箱、公司名
#调用 MCP 工具：`setup_payment`等待：支付方式验证完成
#调用 MCP 工具：`create_subscription`依赖参数：来自第一步的 customer_id
#调用 MCP 工具：`send_email`模板：welcome_email_template
关键技巧：明确步骤依赖关系、在每步加验证、提供失败时的回滚指令。
适用：工作流跨越多个外部服务
## 设计转开发交付流程
### 阶段一：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 在正确的时机加载，不该加载时不加载。
✅ 应该触发的测试用例（至少 10 个）：- "帮我新增一个用户登录接口"- "这个 API 和现有接口会不会冲突"- "帮我写接口文档"
❌ 不应该触发的测试用例：- "帮我写一首诗"- "旧金山的天气怎么样"- "帮我做个 PPT"
快速诊断法：直接问 AI："你什么时候会用 [skill-name] 这个 Skill？" AI 会复述你的 description，根据复述结果判断是否需要调整描述。
测试二：功能测试
运行同一个请求 3-5 次，检查：
输出结果是否一致
API 调用是否成功（0 错误为目标）
关键步骤是否都完成（无遗漏）
测试三：与无 Skill 基线对比
指标 | 无 Skill | 有 Skill | 改善 |
用户需要提供的说明 | 每次都要解释 | 无需解释 | ✅ |
来回对话轮次 | 15 轮 | 2 轮 | ✅ |
API 调用失败次数 | 3 次 | 0 次 | ✅ |
Token 消耗 | 12,000 | 6,000 | ✅ |
信号：Skill 没有自动调用（触发不足）
信号：Skill 总是莫名被调用（过度触发）
信号：Skill 被调用了但 AI 没按步骤执行
你刚才的输出中，[具体描述问题]。请把这个改进固化到 [skill-name] 这个 Skill 文件中，下次遇到同样情况时直接按新方式处理。
这是 Skill 区别于 Slash Command 的核心优势：Skill 是活文档，每次修正都可以沉淀，减少下次犯同样错误的概率。
级别 | 路径 | 适用场景 |
用户级（全局） | ~/.qoder/skills/
| 个人偏好、跨项目通用（如个人设计风格偏好） |
项目级 | <项目根>/.qoder/skills/
| 团队规范、项目特定流程（推荐提交到 Git） |
git add .qoder/skills/git commit -m "feat: add api-standard skill v1.0"git push
git pull
git commit -m "fix(skill/api-standard): 增加对 DELETE 接口的兼容性检查"
在 metadata 中维护版本号，重大变更在 references/CHANGELOG.md 中记录：
metadata: version: 1.2.0 author: 栗子团队
对于 breaking change（会改变 AI 行为的变更），在 description 中注明，并在团队群里发布通知。
如果你的公司使用 Claude 企业版，管理员可以在工作区级别统一部署 Skill，所有成员自动获得，并可集中管理版本更新（2025 年 12 月已上线此功能）。
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-skilldescription: Does things
description: "Does things
---name: my-skilldescription: 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 文件越大越好吗？
不是。建议：
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
---name: skill-name-in-kebab-casedescription: | [做什么] + [什么时候用，含触发词] 不超过 1024 字符，不含 XML 尖括号
license: MITallowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"metadata: author: Your Name / Team version: 1.0.0 mcp-server: server-name category: productivity tags: [tag1, tag2] documentation: https://your-docs.com support: support@company.com---
开始之前
开发过程中
[ ] 文件夹名是 kebab-case（无空格、无大写）
[ ] 主文件名是 SKILL.md（大小写完全正确）
[ ] YAML frontmatter 有 --- 开头和结尾
[ ] name 字段：kebab-case，无空格，无大写
[ ] description 包含"做什么"和"何时用"两部分
[ ] description 不含 XML 尖括号（< >）
[ ] 正文步骤清晰，每步只做一件事
[ ] 关键步骤有错误处理说明
[ ] 包含 1-2 个示例场景
[ ] References 已清晰链接（不要内联大段文档）
测试阶段
发布之后
资源链接
资源 | 地址 | 说明 |
开放 Skill 市场 | https://skills.sh | 当前最流行的开放 Skill 市场 |
Anthropic 官方 Skill 示例库 | github.com/anthropics/skills | 官方示例，可直接 fork 修改 |
Qoder 官方文档 | Qoder 官网 → 文档 → 扩展能力 | Skills 安装指南 |
Qoder 中文 Skill 社区 | 即将上线 | 中英双语，按角色分类 |
本文参考 Anthropic 官方《The Complete Guide to Building Skills for Claude》
粤ICP备14082021号
免费POC，
零成本试错
