知行合一：当人类知识学会自己奔跑--skill
一句话摘要：Skill 是大模型的「外挂技能包」，通过标准化的 YAML + Markdown 文件结构赋予 AI 助手领域专家级能力——如果说大模型是一个聪明但没有实战经验的毕业生，Skill 就是那本让他秒变老司机的「新员工手册」。
想象一下：你教 ChatGPT 画架构图，每次都要重复说一遍"用深色背景、加图标、记得画箭头"……有了 Skill，说一次就够了，而且它比你记得还清楚。
| 属性 | 信息 |
|---|---|
| 领域 | AI 工程 / LLM 应用 / 开发者工具 |
| 关键词 | Skill, MCP, Tool Use, Prompt Engineering, Agent |
| 难度 | 入门 → 中级 |
| 阅读体验 | 约 15 分钟（含边看边试的时间） |
| 最后更新 | 2026-03-02 |
目录
- 1. 概述——Skill 到底是啥
- 2. 全景架构——大模型如何调用 Skill
- 3. Skill 的前世今生
- 4. Skill 的专业定义——文件结构解剖
- 5. 手把手定制你的第一个 Skill
- 6. 多 Skill 协同——高效编排的艺术
- 7. Skill 使用核心技巧——老司机秘籍
- 8. 哲学反思——从 Skill 看 AI 的未来
- 9. 参考资料——致敬先行者
1. 概述
1.1 什么是 Skill？
Skill（技能包）是一种标准化的知识封装格式，它让大模型在特定领域拥有专家级的执行能力。简单来说，Skill 就是一个文件夹，里面装着"该怎么做"的指令、"可以用什么工具"的脚本、以及"参考什么标准"的文档。
这个概念诞生于 AI 辅助编程工具的实践中。当开发者发现大模型虽然"什么都知道一点，但什么都不够专业"时，Skill 应运而生——它不是让模型重新训练，而是在推理时给它一个精确的行动指南。
你可以把 Skill 想象成游戏里的装备系统：大模型本身是一个满级角色，但面对不同副本（任务场景），你需要给它换上不同的装备（Skill）才能发挥最大战力。
💡 人话翻译：Skill 就是写给 AI 的标准操作手册，让它按你的要求做事，而不是自由发挥。
1.2 解决了什么问题？
在 Skill 出现之前，世界是这样的：
- 痛点 1：每次让 AI 画架构图，都要在 Prompt 里写一大段样式要求，像极了每天早上重新教实习生怎么开电脑
- 痛点 2：不同项目、不同团队成员使用 AI 的方式五花八门，生成的文档格式千奇百怪
- 痛点 3：大模型的"好记忆"只限于当前对话窗口，下次打开又是一张白纸，所有定制化偏好归零
然后，Skill 带着它的「标准化 + 持久化 + 可复用」三板斧出现了——
它把你的专业知识、风格偏好、工作流程封装成一个文件夹，AI 每次工作时自动加载，不用你重复交代。一次封装，永久生效，还能分享给团队。
1.3 核心优势
| 优势 | 说明 | 趣味类比 |
|---|---|---|
| 知识持久化 | Skill 文件存储在项目中，不随对话结束而丢失 | 相当于给金鱼装了一块硬盘——终于不用 7 秒一循环了 |
| 质量标准化 | 内置质量检查清单和模板，每次输出都达标 | 像麦当劳的操作手册，无论哪个门店汉堡味道都一样 |
| 团队可复用 | Git 提交后全团队共享同一套 Skill | 一人封装，全队受益——开源精神的极致体现 |
| 渐进式加载 | 元数据→正文→资源文件，按需读取不浪费 Token | 像自助餐，饿了才拿，不是把所有菜搬到桌上 |
2. 全景架构
🏗️ 在深入 Skill 的细节之前，先从上帝视角看一下大模型、MCP、HTTP、Tool Use 和 Skill 之间的关系。
2.0 技术栈一览
| 组件 | 技术 | 说明 |
|---|---|---|
| 🧠 AI 引擎 | Claude / GPT / DeepSeek | 大语言模型，核心推理引擎 |
| 🔍 技能匹配 | Skill Matcher + Skill Registry | 根据用户意图匹配 Skill 并查询注册表 |
| 🌐 协议层 | MCP (Model Context Protocol) | 模型上下文协议，连接模型与外部工具 |
| 🔗 传输层 | HTTP / HTTPS / WebSocket / stdio | 实际通信传输协议 |
| ⚙️ 工具调度 | Tool Dispatcher + Tool Use | 路由 Tool Call 请求到具体工具函数 |
| 📦 技能层 | Skill Pack | 领域知识+工作流+脚本+资源的封装单元 |
| 🖥️ IDE 层 | CodeBuddy / VS Code / Cursor | AI 辅助开发的宿主环境 |
2.1 大模型与 Skill 全景调用关系
下图展示了从用户指令到 Skill 执行的完整调度链路。
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#f0f5ff', 'primaryTextColor': '#1e293b', 'primaryBorderColor': '#3b82f6', 'lineColor': '#64748b', 'secondaryColor': '#f8fafc', 'tertiaryColor': '#ffffff', 'background': '#ffffff', 'mainBkg': '#f0f5ff', 'nodeBorder': '#3b82f6', 'clusterBkg': '#f8fafc', 'clusterBorder': '#cbd5e1', 'titleColor': '#1e40af', 'edgeLabelBackground': '#ffffff', 'nodeTextColor': '#1e293b'}}}%%
graph TB
subgraph USER ["👤 用户层 — User Layer"]
U1["👤 开发者"]
end
subgraph IDE ["🖥️ IDE 层 — Host Environment"]
I1["🖥️ CodeBuddy / Cursor"]
end
subgraph LLM ["🧠 大模型层 — LLM Engine"]
L1["🧠 Claude / GPT<br/>推理引擎"]
L2["🔍 Skill Matcher<br/>技能匹配器"]
L3["📄 Context Builder<br/>上下文组装器"]
end
subgraph SKILL_REG ["📦 技能注册 — Skill Registry"]
R1["📦 Skill Registry<br/>技能注册中心"]
end
subgraph MCP_LAYER ["🌐 MCP 协议层 — Model Context Protocol"]
M1["🌐 MCP Server"]
M2["🔗 MCP Client"]
M3["📋 Capability Discovery<br/>能力发现"]
end
subgraph SKILL ["📦 Skill 层 — Skill Packs"]
S1["📄 SKILL.md<br/>入口定义"]
S2["📚 references/<br/>参考文档"]
S3["⚙️ scripts/<br/>可执行脚本"]
S4["🎨 assets/<br/>模板资源"]
end
subgraph TOOL_DISP ["⚙️ 工具调度 — Tool Dispatcher"]
D1["⚙️ Tool Dispatcher<br/>工具调度器"]
end
subgraph TOOL ["⚡ 工具层 — Tool Use"]
T1["📝 read / write file"]
T2["🔍 search / grep"]
T3["💻 execute command"]
T4["🌐 web fetch"]
end
U1 == "自然语言指令" ==> I1
I1 -- "解析意图" --> L1
L1 -- "匹配 Skill" --> L2
L2 -- "查询注册表" --> R1
R1 -- "返回 Skill 元数据" --> L2
L2 -- "加载 SKILL.md" --> L3
L3 -- "按需加载" --> S1
S1 -- "引用" --> S2
S1 -- "调用" --> S3
S1 -- "使用" --> S4
L3 == "构建上下文 + Tool Call" ==> I1
I1 -- "注册能力" --> M2
M2 -- "stdio/HTTP" --> M1
M1 -- "能力列表" --> M3
M3 -. "发现可用工具" .-> D1
I1 -- "路由请求" --> D1
D1 == "Tool Call" ==> T1
D1 == "Tool Call" ==> T2
D1 -- "Shell" --> T3
D1 -. "HTTP 请求" .-> T4
style U1 fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e293b
style I1 fill:#eff6ff,stroke:#3b82f6,stroke-width:3px,color:#1e293b
style R1 fill:#e0f2fe,stroke:#0284c7,stroke-width:2px,color:#1e293b
style D1 fill:#e0f2fe,stroke:#0284c7,stroke-width:2px,color:#1e293b
style L1 fill:#f5f3ff,stroke:#8b5cf6,stroke-width:3px,color:#1e293b
style L2 fill:#f5f3ff,stroke:#8b5cf6,stroke-width:2px,color:#1e293b
style L3 fill:#f5f3ff,stroke:#8b5cf6,stroke-width:2px,color:#1e293b
style M1 fill:#fffbeb,stroke:#f59e0b,stroke-width:2px,color:#1e293b
style M2 fill:#fffbeb,stroke:#f59e0b,stroke-width:2px,color:#1e293b
style M3 fill:#fffbeb,stroke:#f59e0b,stroke-width:2px,color:#1e293b
style S1 fill:#f0fdf4,stroke:#10b981,stroke-width:3px,color:#1e293b
style S2 fill:#f0fdf4,stroke:#10b981,stroke-width:2px,color:#1e293b
style S3 fill:#f0fdf4,stroke:#10b981,stroke-width:2px,color:#1e293b
style S4 fill:#f0fdf4,stroke:#10b981,stroke-width:2px,color:#1e293b
style T1 fill:#fdf2f8,stroke:#ec4899,stroke-width:2px,color:#1e293b
style T2 fill:#fdf2f8,stroke:#ec4899,stroke-width:2px,color:#1e293b
style T3 fill:#fdf2f8,stroke:#ec4899,stroke-width:2px,color:#1e293b
style T4 fill:#fdf2f8,stroke:#ec4899,stroke-width:2px,color:#1e293b
图 1：大模型 × MCP × Skill × Tool Use 全景调用关系——从用户指令到工具执行的完整链路
图中关键路径解读：
- 用户→IDE→LLM→Skill（主调用链 + 知识加载链）：用户的自然语言指令通过 IDE 传递给大模型，Skill Matcher 通过 Skill Registry 匹配对应的 Skill，Context Builder 按三级渐进机制加载 Skill 内容——先读元数据，再读 SKILL.md 正文，最后按需读取 references/scripts/assets
- LLM→IDE→MCP→Tool（工具执行链）：LLM 生成 Tool Call 请求后交给 IDE，IDE 通过 MCP 协议进行能力发现和注册，Tool Dispatcher 将请求路由到具体的工具函数
- Skill Registry ↔ MCP 协议（能力桥梁）：Skill Registry 管理 Skill 元数据供 LLM 匹配，MCP 协议管理工具能力供 Dispatcher 调度——两者分别服务于"知识选择"和"工具执行"
🔍 架构设计的精妙之处：Skill 和 Tool 是两个正交的概念——Skill 提供"知道该做什么"（领域知识），Tool 提供"能做什么"（执行能力）。同一个 Skill 可以在不同的 Tool 环境中运行，同一个 Tool 也可以被不同的 Skill 复用。Skill Registry 和 MCP Capability Discovery 分别负责"知识注册"和"工具注册"，共同构成系统的完整能力目录。
2.2 MCP、HTTP 与 Skill 的调用时序
从一个具体请求的视角，看看各组件之间的交互时序：
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#f0f5ff', 'primaryTextColor': '#1e293b', 'primaryBorderColor': '#3b82f6', 'lineColor': '#64748b', 'secondaryColor': '#f8fafc', 'tertiaryColor': '#ffffff', 'background': '#ffffff', 'mainBkg': '#f0f5ff', 'nodeBorder': '#3b82f6', 'actorBkg': '#f0f5ff', 'actorBorder': '#3b82f6', 'actorTextColor': '#1e293b', 'actorLineColor': '#64748b', 'signalColor': '#475569', 'signalTextColor': '#1e293b', 'labelBoxBkgColor': '#f0f5ff', 'labelBoxBorderColor': '#3b82f6', 'labelTextColor': '#1e40af', 'loopTextColor': '#b45309', 'noteBkgColor': '#f5f3ff', 'noteTextColor': '#1e293b', 'noteBorderColor': '#8b5cf6', 'activationBkgColor': '#e0f2fe', 'activationBorderColor': '#3b82f6', 'sequenceNumberColor': '#ffffff'}}}%%
sequenceDiagram
participant U as 👤 Developer
participant IDE as 🖥️ IDE
participant LLM as 🧠 LLM Engine
participant SK as 📦 Skill Pack
participant MCP as 🌐 MCP Server
participant FS as 📂 File System
U->>+IDE: 📨 "根据 git diff 生成提交信息"
IDE->>+LLM: 🔗 转发请求 + 系统提示词
Note over LLM: 🔍 扫描可用 Skill 列表
LLM->>LLM: 匹配 commit-message Skill
LLM->>+SK: 📄 读取 SKILL.md
SK-->>-LLM: 返回工作流指令
Note over LLM: 📋 解析 Workflow Steps
LLM->>+SK: 📚 读取 references/
SK-->>-LLM: 返回提交规范
LLM->>+SK: 🎨 读取 assets/（如有）
SK-->>-LLM: 返回模板
Note over LLM: 🧠 组装上下文，开始生成
LLM->>+MCP: ⚡ Tool Call: execute_command
MCP->>+FS: 💻 git diff --cached
FS-->>-MCP: ✅ 返回 diff 内容
MCP-->>-LLM: 返回结果
LLM->>+MCP: ⚡ Tool Call: write_to_file
MCP->>+FS: 📝 写入 commit-message.txt
FS-->>-MCP: ✅ 写入成功
MCP-->>-LLM: 返回结果
LLM-->>-IDE: 🚀 完成
IDE-->>-U: 📊 展示生成的提交信息
图 2：一次 Skill 调用的完整时序——从"生成提交信息"到输出结果的全链路
💡 关键洞察：LLM 不是一次性读完所有 Skill 文件，而是先读 SKILL.md 获取工作流，再根据当前步骤按需加载 references 和 assets。这种渐进式加载有效控制了 Token 消耗。
3. Skill 的前世今生
🗺️ 要理解 Skill，先得知道它是怎么一步步演化来的。
3.1 前 Skill 时代：Prompt Engineering（2022-2023）
一切始于 Prompt Engineering——开发者发现，给大模型的提示词越详细，输出质量越高。于是出现了所谓的「超级 Prompt」，动辄 200 行的样式要求。问题：这些 Prompt 只存在于对话历史中，换个窗口就没了。
3.2 System Prompt 时代（2023）
随着 OpenAI API 引入 system 角色，IDE 插件开始支持自定义 System Prompt 文件（如 .cursorrules）。进步：指令持久化了。问题：还是一坨大文本，没有结构化，也无法按需加载。
3.3 Skill 的诞生（2024-2025）
MCP（Model Context Protocol）协议和 Skill 体系几乎同时出现，标志着 AI 辅助开发进入结构化知识管理时代：
| 演进 | 创新点 | 解决的问题 |
|---|---|---|
| 文件夹结构 | 从单文件→目录结构 | 知识组织混乱 |
| YAML 元数据 | name + description 触发词，AI 自动匹配 | 手动选择 Prompt |
| 三级加载 | 元数据→正文→资源，渐进式读取 | Token 浪费 |
| 脚本集成 | scripts/ 可放可执行代码 | 纯文本无法执行 |
| 模板资产 | assets/ 存放模板、图片等 | 每次从零生成 |
3.4 MCP 与 Skill 的关系
MCP 和 Skill 不是竞争关系，而是互补关系：
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#f0f5ff', 'primaryTextColor': '#1e293b', 'primaryBorderColor': '#3b82f6', 'lineColor': '#64748b', 'secondaryColor': '#f8fafc', 'tertiaryColor': '#ffffff', 'background': '#ffffff', 'mainBkg': '#f0f5ff', 'nodeBorder': '#3b82f6', 'clusterBkg': '#f8fafc', 'clusterBorder': '#cbd5e1', 'titleColor': '#1e40af', 'edgeLabelBackground': '#ffffff', 'nodeTextColor': '#1e293b'}}}%%
graph LR
subgraph KNOW ["📚 知识层 — What & How"]
K1["📄 SKILL.md<br/>工作流指令"]
K2["📚 references/<br/>参考规范"]
end
subgraph EXEC ["⚡ 执行层 — With What"]
E1["🌐 MCP Server<br/>能力注册"]
E2["⚙️ Tool Use<br/>函数调用"]
end
subgraph BRAIN ["🧠 大脑 — LLM"]
B1["🧠 LLM 推理引擎"]
end
K1 == "告诉 LLM 该做什么" ==> B1
K2 -- "提供参考标准" --> B1
B1 == "调用工具去执行" ==> E2
E1 -- "注册可用能力" --> B1
E2 -. "通过 MCP 协议" .-> E1
style K1 fill:#f0fdf4,stroke:#10b981,stroke-width:3px,color:#1e293b
style K2 fill:#f0fdf4,stroke:#10b981,stroke-width:2px,color:#1e293b
style E1 fill:#fffbeb,stroke:#f59e0b,stroke-width:2px,color:#1e293b
style E2 fill:#fdf2f8,stroke:#ec4899,stroke-width:2px,color:#1e293b
style B1 fill:#f5f3ff,stroke:#8b5cf6,stroke-width:3px,color:#1e293b
图 3：Skill（知识层）与 MCP/Tool Use（执行层）的互补关系
- Skill → 回答「做什么」和「怎么做」——领域知识、工作流、质量标准
- MCP/Tool Use → 回答「用什么做」——读写文件、执行命令、网络请求
- LLM → 负责「理解」和「决策」——理解意图，选择 Skill，调用 Tool
4. Skill 的专业定义
⚙️ 现在让我们打开引擎盖，看看一个标准 Skill 的内部结构。
4.1 标准目录结构
skill-name/
├── SKILL.md # （必需）入口文件，YAML 元数据 + 工作流指令
├── scripts/ # （可选）可执行脚本
│ └── *.py / *.sh
├── references/ # （可选）参考文档，按需加载
│ └── *.md
└── assets/ # （可选）模板、图片等资源
└── template.html / ...
| 目录 | 必需性 | 职责 | 加载方式 |
|---|---|---|---|
| SKILL.md | ✅ 必需 | YAML 元数据 + 工作流正文 | 触发时自动加载 |
| scripts/ | 可选 | 确定性执行的代码脚本 | 直接执行 |
| references/ | 可选 | AI 参考的文档/规范 | 按需读入上下文 |
| assets/ | 可选 | 模板、图片、字体等 | 被复制/修改到输出中 |
💡 为什么只有四个东西？ 任何领域知识都可以分解为：一个「总纲领」（SKILL.md），一些「参考手册」（references/），一些「工具」（scripts/），和一些「原材料」（assets/）。这是社区反复迭代后的极简设计。
4.2 SKILL.md 剖析
SKILL.md 由两部分组成：
Part 1: YAML Frontmatter（元数据）
---
name: skill-creator
description: "Create new skills, modify and improve existing skills,
and measure skill performance. Use when users want to create a skill
from scratch, update or optimize an existing skill, run evals to test
a skill, or optimize a skill's description for better triggering accuracy."
---
| 字段 | 作用 | 要求 |
|---|---|---|
name | Skill 唯一标识 | 全小写，短横线分隔 |
description | 触发条件和功能描述 | 含中英文触发词，~100 词 |
description 是 Skill 匹配的核心——LLM 根据它判断是否激活该 Skill。
Part 2: Markdown 正文（工作流指令）
# Skill 标题
## Quick Reference ← 指向 references/ 和 assets/ 的索引
## Overview ← 能力概述
## When to Use ← 适用/不适用场景
## Workflow
### Step 1: 分析需求
### Step 2: 准备资源
### Step 3: 生成产出
### Step 4: 质量检查
## Dependencies ← 外部依赖说明
4.3 真实案例：三种典型 Skill 的对比
以社区中广泛使用的三类 Skill 为例，展示不同领域 Skill 的结构差异：
| 维度 | 🛠️ skill-creator | 📝 commit-message | 🧪 code-review |
|---|---|---|---|
| 核心能力 | 创建、测试和迭代优化 Skill | 根据 Git diff 生成规范的 commit message | 自动审查代码质量，输出改进建议 |
| references/ | 1 个 schemas.md（定义全部 JSON 数据结构） | 1 个 conventional-commits.md（提交规范） | 2 个文件（代码规范 + 常见反模式） |
| scripts/ | 8 个 Python 脚本（评估、基准测试、报告生成） | 无 | 1 个 lint 聚合脚本 |
| assets/ | 2 个 HTML（评估查看器 + 报告模板） | 无 | 1 个 review-template.md |
| agents/ | 3 个子 Agent（analyzer / comparator / grader） | 无 | 无 |
| Skill 类型 | 侧重「脚本执行 + 评估闭环」 | 侧重「纯知识规范」（无脚本无模板） | 侧重「规范参考 + 模板输出」 |
三个案例的设计启示：
- skill-creator 是"重型 Skill"的代表——大量脚本+子 Agent+评估流水线，适合需要迭代验证的复杂场景。注意它额外使用了
agents/目录存放子 Agent 定义，这是对标准四目录结构的扩展，适用于需要多 Agent 协作的高级场景 - commit-message 是"轻量 Skill"的典范——只需一个 SKILL.md + 一个参考规范，Skill 不一定要"大而全"
- code-review 是"中间路线"——参考文档+模板，平衡了灵活性和标准化
🔍 核心原则：没有两个 Skill 长得一模一样。根据领域特点决定各目录的权重——简单任务别过度设计，复杂任务别偷工减料。
4.4 三级渐进加载机制
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#f0f5ff', 'primaryTextColor': '#1e293b', 'primaryBorderColor': '#3b82f6', 'lineColor': '#64748b', 'secondaryColor': '#f8fafc', 'tertiaryColor': '#ffffff', 'background': '#ffffff', 'mainBkg': '#f0f5ff', 'nodeBorder': '#3b82f6', 'clusterBkg': '#f8fafc', 'clusterBorder': '#cbd5e1', 'titleColor': '#1e40af', 'edgeLabelBackground': '#ffffff', 'nodeTextColor': '#1e293b'}}}%%
graph LR
A["📋 Level 1<br/>元数据 ~100 词"] == "始终在上下文" ==> B["📄 Level 2<br/>SKILL.md 正文 <5K 词"]
B == "按需读入上下文" ==> C["📚 Level 3<br/>references/ scripts/ assets/"]
style A fill:#eff6ff,stroke:#3b82f6,stroke-width:3px,color:#1e293b
style B fill:#f5f3ff,stroke:#8b5cf6,stroke-width:3px,color:#1e293b
style C fill:#f0fdf4,stroke:#10b981,stroke-width:2px,color:#1e293b
图 4：三级渐进加载——从元数据到完整资源的按需读取
系统可以同时挂载数十个 Skill 的元数据（Level 1），但只有被触发的 Skill 才会占用上下文窗口。就像手机上装了 100 个 App，但只有正在使用的才占内存。
5. 手把手定制你的第一个 Skill
🛠️ 理论够了，撸起袖子实战。本节提供两种方式——手工创建和借助 Skill Creator 自动创建。
5.1 方式一：手工创建（适合简单 Skill）
Step 1：明确定位
在动手之前，先回答三个问题：
| 问题 | 示例回答 |
|---|---|
| 解决什么问题？ | 让 AI 根据 Git diff 自动生成 Conventional Commits 格式的提交信息 |
| 触发条件是什么？ | "commit message、提交信息、git commit" |
| 需要什么资源？ | Conventional Commits 规范文档 |
⚠️ 常见错误：一个 Skill 应该只做一件事并做到极致。试图同时处理架构图+PPT+文档的 Skill，该拆。
Step 2：创建目录
mkdir -p .codebuddy/skills/my-skill/{references,scripts,assets}
touch .codebuddy/skills/my-skill/SKILL.md
Step 3：编写 SKILL.md
以「Commit Message 生成器」为例：
---
name: commit-message
description: "Use this skill when users need to generate commit messages
following Conventional Commits specification. Trigger when: 'commit message',
'提交信息', 'git commit', '写提交', 'conventional commit'."
---
# Commit Message Generator
## Quick Reference
| Task | Guide |
|------|-------|
| 提交规范 | Read [references/conventional-commits.md] |
## Workflow
### Step 1: 读取 git diff 或用户描述的变更内容
### Step 2: 识别变更类型（feat/fix/refactor/docs/chore 等）
### Step 3: 确定影响范围（scope）
### Step 4: 生成符合 Conventional Commits 格式的提交信息
### Step 5: 如有 Breaking Changes，补充 BREAKING CHANGE footer
Step 4：编写参考文档和模板
在 references/ 中放 AI 工作时需要参考的规范，在 assets/ 中放输出模板。
Step 5：description 编写七条黄金法则
| 法则 | ✅ 正例 | ❌ 反例 |
|---|---|---|
| 含触发关键词 | "Trigger: '架构图', 'architecture'" | "生成图" |
| 说明能力边界 | "commit messages following Conventional Commits" | "各种文本" |
| 中英双语 | "'写Wiki', 'AI Wiki'" | 只写英文 |
| 控制 100 词 | 精炼 2-3 句 | 500 字论文 |
| 避免泛化 | "PPTX presentation file" | "任何文件" |
| 含输出格式 | "produces HTML pages" | 不提格式 |
| 适度"主动" | "Make sure to use this skill whenever the user mentions dashboards" | 过于被动，导致该触发时不触发 |
💡 来自 skill-creator 的经验：description 宁可"主动"一点，因为 AI 当前有"欠触发"倾向——宁可多匹配，也不要在用户需要时沉默。
5.2 方式二：使用 Skill Creator（推荐，适合复杂 Skill）
手工创建适合轻量 Skill，但如果你的 Skill 涉及复杂工作流、需要评估迭代，那么推荐使用 skill-creator ——一个专门用来「创建 Skill 的 Skill」。
什么是 Skill Creator？
Skill Creator 是 Anthropic 官方提供的元技能（Meta-Skill），它的核心理念是：用 AI 来创建给 AI 用的技能包。它内置了完整的 Skill 创建→测试→评估→迭代优化闭环。
Skill Creator 的工作流程
| 阶段 | 做什么 | AI 的角色 |
|---|---|---|
| 1. 捕获意图 | 明确 Skill 功能、触发条件、输出格式 | AI 主动提问，引导你厘清需求 |
| 2. 访谈研究 | 讨论边界情况、输入输出、成功标准 | AI 查找文档、研究最佳实践 |
| 3. 编写草稿 | 自动生成 SKILL.md + 目录结构 | AI 根据访谈结果一键生成 |
| 4. 创建测试 | 设计 2-3 个真实用户场景的测试用例 | AI 提议测试用例，你确认 |
| 5. 并行评估 | 对比"有 Skill"和"无 Skill"的输出质量 | AI 同时启动两组测试，自动对比 |
| 6. 迭代改进 | 根据评估反馈优化 Skill | AI 分析差距，提出改进方案 |
| 7. 扩大测试 | 增加测试用例，确保泛化能力 | 重复 5-6 直到满意 |
实战：用 Skill Creator 创建一个 Code Review Skill
# 第一轮对话：启动创建
"我想创建一个 code-review Skill，能自动审查 Python 代码的质量"
# AI 会主动访谈你：
# - 关注哪些维度？（性能/安全/可读性/命名规范？）
# - 输出什么格式？（Markdown 报告/内联注释/JSON？）
# - 有没有团队已有的代码规范？
# 第二轮对话：确认草稿
"大纲 OK，请生成 SKILL.md 草稿"
# AI 自动生成完整的目录结构：
# code-review/
# ├── SKILL.md
# ├── references/
# │ ├── python-style-guide.md
# │ └── common-antipatterns.md
# └── assets/
# └── review-template.md
# 第三轮对话：测试评估
"请创建测试用例并运行评估"
# AI 生成测试用例，并行运行"有/无 Skill"对比测试，
# 生成可视化评估报告，让你直观看到 Skill 的效果
# 第四轮对话：迭代优化
"安全维度的审查不够深入，参考 OWASP Top 10 加强"
# AI 更新 references/，优化工作流，重新评估
Skill Creator 的独门利器
| 特性 | 说明 |
|---|---|
| A/B 对比测试 | 同时运行"有 Skill"和"无 Skill"版本，量化 Skill 带来的提升 |
| 子 Agent 评估 | 内置 analyzer（分析输出）、comparator（对比差异）、grader（打分）三个评估 Agent |
| Description 优化器 | 自动生成触发词测试，优化 description 的匹配准确率 |
| 评估可视化 | 生成 HTML 评估报告，一目了然地查看每个测试用例的表现 |
| 基准测试 | 多轮迭代的性能基准对比，确保每次修改都是在进步 |
💡 选择建议：如果你的 Skill 只是简单的知识规范（如 commit-message），手工创建 5 分钟搞定；如果涉及复杂工作流、需要反复调优（如 code-review、架构图生成），用 Skill Creator 能节省大量试错时间。
6. 多 Skill 协同
🎼 单个 Skill 是独奏，多个 Skill 协同才是交响乐。
6.1 跨 Skill 调用实例
以一个典型的文档生成场景为例——tech-wiki Skill 在生成技术文档时，调用 diagram-generator Skill 自动绘制架构图：
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#f0f5ff', 'primaryTextColor': '#1e293b', 'primaryBorderColor': '#3b82f6', 'lineColor': '#64748b', 'secondaryColor': '#f8fafc', 'tertiaryColor': '#ffffff', 'background': '#ffffff', 'mainBkg': '#f0f5ff', 'nodeBorder': '#3b82f6', 'clusterBkg': '#f8fafc', 'clusterBorder': '#cbd5e1', 'titleColor': '#1e40af', 'edgeLabelBackground': '#ffffff', 'nodeTextColor': '#1e293b'}}}%%
graph LR
subgraph WIKI ["📝 tech-wiki Skill"]
W1["📋 分析主题"] --> W2["📐 构建大纲"]
W2 --> W3["🏗️ 生成架构图"]
W3 --> W4["📊 Mermaid 图表"]
W4 --> W5["✍️ 编写正文"]
W5 --> W6["📦 组装输出"]
end
subgraph DIAG ["🎨 diagram-generator Skill"]
A1["📄 读取模板"] --> A2["🎨 生成图表"]
A2 --> A3["📸 导出 PNG"]
end
W3 == "调用" ==> A1
A3 == "返回 PNG" ==> W4
style W1 fill:#f5f3ff,stroke:#8b5cf6,stroke-width:2px,color:#1e293b
style W2 fill:#f5f3ff,stroke:#8b5cf6,stroke-width:2px,color:#1e293b
style W3 fill:#f5f3ff,stroke:#8b5cf6,stroke-width:3px,color:#1e293b
style W4 fill:#f5f3ff,stroke:#8b5cf6,stroke-width:2px,color:#1e293b
style W5 fill:#f5f3ff,stroke:#8b5cf6,stroke-width:2px,color:#1e293b
style W6 fill:#f5f3ff,stroke:#8b5cf6,stroke-width:2px,color:#1e293b
style A1 fill:#f0fdf4,stroke:#10b981,stroke-width:2px,color:#1e293b
style A2 fill:#f0fdf4,stroke:#10b981,stroke-width:2px,color:#1e293b
style A3 fill:#f0fdf4,stroke:#10b981,stroke-width:2px,color:#1e293b
图 5：tech-wiki 与 diagram-generator 的跨 Skill 协作流程
6.2 协作设计模式
| 模式 | 描述 | 示例 |
|---|---|---|
| 嵌套调用 | Skill A 的某个 Step 显式调用 Skill B | tech-wiki → diagram-generator |
| 共享资源 | 多个 Skill 引用相同的 references | 共用 coding-standards.md |
| 管道串联 | A 的输出作为 B 的输入 | 代码分析→API 文档→Wiki |
| 并行独立 | 各自处理不同部分 | 同时生成代码+测试+文档 |
6.3 管理最佳实践
- 命名空间：
领域-功能格式（code-review、commit-message、api-doc） - 单一职责：宁可多建几个小 Skill 也不要一个大而全
- 松耦合：Skill 之间通过文件系统交互，不依赖内部 API
- 版本控制：Skill 文件跟项目代码一起 Git 管理
- 文档先行：先写 description，确保触发条件清晰
7. Skill 使用核心技巧
🎯 本节是全文重点中的重点——从"能用"到"用好"的进阶秘籍。每一条都来自实战经验的提炼。
7.1 触发技巧：让 Skill 精准命中
技巧 1：使用精确触发词
| 场景 | ❌ 模糊说法 | ✅ 精确触发 |
|---|---|---|
| 生成架构图 | "帮我画个图" | "生成一张架构图，用深色科技风" |
| 写提交信息 | "帮我提交代码" | "根据 git diff 生成 commit message" |
| 做代码审查 | "看看我的代码" | "对这个 PR 做一次 code review" |
技巧 2：@mention 直接引用 Skill 路径
@.codebuddy/skills/commit-message 根据当前 git diff 生成提交信息
绕过关键词匹配，直接指定 Skill——100% 命中率，这是最可靠的触发方式。
技巧 3：描述期望的输出格式
帮我做一次 **code review**，重点关注安全漏洞和性能问题，输出 Markdown 报告
明确输出格式帮助 AI 选对 Skill。
7.2 上下文管理：让 Skill 读到该读的
技巧 4：引导 AI 按需加载 references
Skill 的 references/ 不会一次全部加载。显式引导：
请参考 references/cloud-icons-guide.md，为架构图每个节点添加专业图标
技巧 5：分步骤交互，不要一次性倾倒
按 Skill 的 Workflow 步骤逐轮推进，而非一条消息交代所有需求：
# 第一轮：明确需求
"根据 git diff 生成 **commit message**，遵循 Conventional Commits 规范"
# 第二轮：补充上下文
"这次改动涉及用户认证模块的重构，scope 是 auth"
# 第三轮：微调输出
"body 部分再补充一下 Breaking Change 的影响说明"
技巧 6：用 @attach 提供项目上下文
@src/api/routes.ts 参考这些路由定义，生成 API 文档
7.3 质量控制：让输出达到专业级
技巧 7：利用内置质量检查清单
完成初稿后显式要求自检：
请对照 SKILL.md 中的质量检查清单，检查一遍输出是否合格
技巧 8：提供反面示例（Few-shot Negative）
"不要什么"比"要什么"更有效：
注意：不要使用白色背景，不要超过 15 个节点，不要用默认 Mermaid 主题
技巧 9：迭代优化而非推倒重来
# ❌ 低效
"架构图不好看，重新画"
# ✅ 高效
"架构图整体不错，Redis 节点边框改红色，数据流箭头加标签"
保留好的部分，只修改不满意的部分，效率提升 10 倍。
7.4 定制进阶：让 Skill 更懂你
技巧 10：在 references/ 中沉淀团队知识
规则：如果你发现同一句话对 AI 说了 3 次，就该写进 references/。
| 重复的口头指令 | 应该沉淀的文件 |
|---|---|
| "用我们公司的配色" | references/brand-colors.md |
| "按我们的代码规范" | references/code-style.md |
| "部署到 K8s 集群" | references/deploy-guide.md |
技巧 11：用 assets/ 模板固化最佳实践
团队的标准化输出格式放进 assets/，AI 每次基于模板生成，保证格式一致。
技巧 12：用 scripts/ 实现确定性操作
不该 AI 自由发挥的操作（如文件格式转换、截图）写成脚本：
# scripts/html2png.py — 确定性地将 HTML 转为 PNG
# AI 不需要"想"怎么截图，直接执行就行
7.5 效率提升：少花 Token，多出活
技巧 13：善用三级加载，减少 Token 消耗
在 SKILL.md 的 Workflow 中，只在需要的 Step 里引用对应文件：
### Step 3: 生成架构图
Read [references/design-spec.md] ← 只在这一步加载
### Step 5: 编写正文
（不需要设计规范，不加载）
技巧 14：把大参考文档拆成小文件
# ❌ 低效：一个大文件全部加载
references/complete-guide.md # 5000 行
# ✅ 高效：多个小文件按需加载
references/
├── color-palette.md # 200 行
├── layout-rules.md # 300 行
├── icon-guide.md # 500 行
└── typography.md # 150 行
技巧 15：复用已有 Skill
创建新 Skill 前先检查：
ls .codebuddy/skills/
head -5 .codebuddy/skills/*/SKILL.md
7.6 调试技巧：Skill 不按预期工作时
技巧 16：检查 description 关键词覆盖
# 问题：用户说"画流程图"但 Skill 没触发
# 原因：description 里只写了"架构图"
# 修复：添加缺失的触发词
description: "... '架构图', '流程图', 'flow chart'..."
技巧 17：检查 SKILL.md 中的引用路径
# ❌ 错误：绝对路径
Read [/Users/xxx/skills/my-skill/references/guide.md]
# ✅ 正确：相对路径
Read [references/guide.md]
技巧 18：用"干跑"模式验证
请按照 @.codebuddy/skills/my-skill 的 Workflow，
告诉我你打算读取哪些文件、执行哪些步骤、生成什么输出。
（先不实际执行，只输出计划）
7.7 技巧速查表
| # | 技巧 | 类别 | 一句话总结 |
|---|---|---|---|
| 1 | 精确触发词 | 触发 | 用 description 里的关键词发起请求 |
| 2 | @mention 路径 | 触发 | 直接引用 Skill 目录，100% 命中 |
| 3 | 描述输出格式 | 触发 | 明确期望格式帮 AI 选对 Skill |
| 4 | 引导按需加载 | 上下文 | 显式引用 references/ 中的文件 |
| 5 | 分步骤交互 | 上下文 | 按 Workflow 步骤逐轮推进 |
| 6 | @attach 文件 | 上下文 | 用 @ 引用项目中的已有文件 |
| 7 | 自检清单 | 质量 | 让 AI 对照清单自查 |
| 8 | 反面示例 | 质量 | "不要什么"比"要什么"更有效 |
| 9 | 迭代优化 | 质量 | 小改比推倒重来效率高 10 倍 |
| 10 | 沉淀 references | 定制 | 重复说 3 次的话写成文件 |
| 11 | 模板固化 | 定制 | 标准化输出放 assets/ |
| 12 | 脚本确定性 | 定制 | 不该自由发挥的操作写脚本 |
| 13 | 按需加载 | 效率 | 只在需要的 Step 里 Read |
| 14 | 分拆大文件 | 效率 | 小文件按需加载更省 Token |
| 15 | 复用 Skill | 效率 | 新建前先检查已有的 |
| 16 | 检查关键词 | 调试 | 没触发？看 description 触发词 |
| 17 | 检查路径 | 调试 | 加载失败？看相对路径 |
| 18 | 干跑验证 | 调试 | 先输出计划再实际执行 |
8. 哲学反思
🔭 工具塑造思维，思维反过来创造新工具。
8.1 从 Skill 看"知识的可执行化"
Skill 本质上做了一件很深刻的事：把隐性知识变成了可执行的显性知识。
传统知识管理（Confluence、内部文档）是"人读给自己看的"——依赖读者的理解和执行力。而 Skill 是"写给 AI 看的"——它必须足够精确、结构化、无歧义，因为执行者是一个"聪明但死板"的语言模型。
这种转变逼着我们重新审视自己的知识：你以为你知道怎么画架构图，但当你试图把它写成 Skill 时，你会发现有 80% 的决策是"感觉"——你从来没有明确定义过"什么时候用粗箭头，什么时候用虚线"。Skill 迫使这些"感觉"变成"规则"。
某种意义上，编写 Skill 的过程就是知识考古的过程——挖掘埋藏在直觉中的专业判断，把它变成可传承、可复用的文字。
8.2 未解之题
「好的技术回答旧问题，伟大的技术提出新问题。」
- Skill 的粒度悖论：太细碎则管理成本高，太粗放则不够专业。最佳粒度在哪里？目前没有公认答案
- Skill 间的冲突解决：当两个 Skill 的 description 都匹配当前任务时，谁优先？如何避免"多个 Skill 抢活"？
- Skill 的过期问题：技术迭代很快，写好的 Skill 多久会过时？谁负责更新？这本质上是知识管理的老问题
8.3 未来展望
Skill 目前还处于"手工作坊"阶段——每个 Skill 都是手写的。但可以预见的趋势是：
- Skill 生成 Skill：让 AI 根据用户的使用模式，自动提炼出新的 Skill（Meta-Skill）
- Skill 市场：像 npm/pip 一样的 Skill 包管理器，
skill install code-review@v3 - 自适应 Skill：Skill 根据执行反馈自动优化自己的 Workflow，从"静态手册"进化为"动态专家"
💭 结语：当我们教会 AI 使用 Skill，我们其实在做一件更根本的事——梳理和结构化人类的专业知识。也许 Skill 最大的价值不在于让 AI 更强，而在于迫使我们搞清楚自己到底「知道什么」。这个过程本身，比任何工具都更有价值。
9. 参考资料
📚 站在巨人的肩膀上——不过先确认巨人没有站在流沙上。
协议与规范
- Anthropic, "Model Context Protocol (MCP) Specification", 2024. modelcontextprotocol.io/
- 📌 推荐理由：MCP 是理解 Skill 执行层的关键协议，读完就明白 Tool Use 的运作机制
- OpenAI, "Function Calling / Tool Use Documentation", 2024. platform.openai.com/docs/guides…
- 📌 推荐理由：Tool Use 的鼻祖级文档，理解 AI 如何调用外部工具
Skill 实践
- CodeBuddy Skills Documentation
- 📌 适合：想要从零创建 Skill 的开发者
- Cursor
.cursorrulesCommunity Collection, GitHub- 📌 亮点：大量社区贡献的 System Prompt 规则，可作为 Skill 的灵感来源
推荐阅读
- Simon Willison, "Prompt Engineering and LLM Customization", 2024
- 📌 亮点：从 Prompt Engineering 到结构化知识管理的演进思考
- Harrison Chase, "Building LLM Applications with LangChain", 2024
- 📌 亮点：Agent + Tool Use 的工程实践，与 Skill 理念相通
