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

在 AI 原生工作流加速普及的今天，掌握 Skill 已不再是开发者的专属能力，而是产品、运营、设计乃至技术管理者提升人机协同效能的核心职业素养。它直接决定你能否把模糊需求转化为稳定、可复用、可协作的 AI 执行单元，从而在项目交付中显著提升质量一致性、降低沟通成本、规避重复试错。一、理解 Skill 的本质：菜单与菜谱的比喻

没有菜单的餐馆，会发生什么？

想象你走进一家餐馆，直接对厨师说："帮我做一道红烧肉。"

结果——厨师按自己的理解自由发挥。你收到的可能是完全不合口味的东西。

这正是我们每天在用 AI 时遇到的问题。

你向 AI 传达了需求，AI 却按自己的理解执行，导致你不得不反复修正输出，持续"调教"——高成本、低确定性、难以复现。

有了菜谱，一切就不同了

Skill 就是 AI 世界里的菜谱（Recipe）。

当 AI 有了一份清晰的菜谱，它就知道：

• 这道菜的标准做法是什么

• 哪些步骤是必须的

• 用哪些食材、什么火候、什么顺序

你作为顾客（用户）只需点菜，AI（厨师）就能按菜谱稳定交付。

整个 AI 工具生态的类比映射

MCP 提供专业厨房——让 AI 能访问你的工具、数据和外部服务。

Skill 提供菜谱——告诉 AI 如何将这些工具用好、按什么工作流执行。两者结合，才能让用户无需每次从头解释，AI 也能稳定交付高质量结果。

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

Skill 的本质定义

Skill 是一个开放标准的文件夹，包含一套告诉 AI 如何处理特定任务或工作流的指令。它是目前最强大的 AI 定制方式之一：教 AI 一次，永久受益——不再需要在每次对话中重新解释你的偏好、流程和领域知识。

Skill 的文件结构

⚠️ 三个命名硬规则：

三级渐进式披露机制（Progressive Disclosure）

这是 Skill 最核心的工作原理，决定了它既节省上下文，又能承载复杂知识：

这个机制的三大优势：

Skill 的跨平台兼容性

Skill 是开放标准，在以下环境中完全兼容：

• ✅ Qoder（Quest 模式、AIDE 模式、CLI）

• ✅ Claude.ai 网页端

• ✅ Claude Code CLI

• ✅ JetBrains 插件（即将支持）

• ✅ Claude API（通过 container.skills 参数）

创建一次，所有平台通用。

三、三个关键问题：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

执行后，按交互提示：

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（含官方规范）

完整文件格式

参考资料

• 详见 references/api-guide.md
  

可选字段（完整版）

禁止事项

写好 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 协调

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

模式三：迭代优化循环

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

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

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

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

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

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

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

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

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

快速诊断法：直接问 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 治理

两级安装策略

# 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 格式错误：

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 实践：

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

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

Frontmatter 完整速查

上线前完整 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 字段