当人类知识学会自己奔跑--skill

知行合一：当人类知识学会自己奔跑--skill

一句话摘要：Skill 是大模型的「外挂技能包」，通过标准化的 YAML + Markdown 文件结构赋予 AI 助手领域专家级能力------如果说大模型是一个聪明但没有实战经验的毕业生，Skill 就是那本让他秒变老司机的「新员工手册」。

想象一下：你教 ChatGPT 画架构图，每次都要重复说一遍"用深色背景、加图标、记得画箭头"......有了 Skill，说一次就够了，而且它比你记得还清楚。

属性	信息
领域	AI 工程 / LLM 应用 / 开发者工具
关键词	Skill, MCP, Tool Use, Prompt Engineering, Agent
难度	入门 → 中级
阅读体验	约 15 分钟（含边看边试的时间）
最后更新	2026-03-02

---

目录

• [1. 概述------Skill 到底是啥](#1. 概述——Skill 到底是啥 "#1-%E6%A6%82%E8%BF%B0")
• [2. 全景架构------大模型如何调用 Skill](#2. 全景架构——大模型如何调用 Skill "#2-%E5%85%A8%E6%99%AF%E6%9E%B6%E6%9E%84")
• [3. Skill 的前世今生](#3. Skill 的前世今生 "#3-skill-%E7%9A%84%E5%89%8D%E4%B8%96%E4%BB%8A%E7%94%9F")
• [4. Skill 的专业定义------文件结构解剖](#4. Skill 的专业定义——文件结构解剖 "#4-skill-%E7%9A%84%E4%B8%93%E4%B8%9A%E5%AE%9A%E4%B9%89")
• [5. 手把手定制你的第一个 Skill](#5. 手把手定制你的第一个 Skill "#5-%E6%89%8B%E6%8A%8A%E6%89%8B%E5%AE%9A%E5%88%B6%E4%BD%A0%E7%9A%84%E7%AC%AC%E4%B8%80%E4%B8%AA-skill")
• [6. 多 Skill 协同------高效编排的艺术](#6. 多 Skill 协同——高效编排的艺术 "#6-%E5%A4%9A-skill-%E5%8D%8F%E5%90%8C")
• [7. Skill 使用核心技巧------老司机秘籍](#7. Skill 使用核心技巧——老司机秘籍 "#7-skill-%E4%BD%BF%E7%94%A8%E6%A0%B8%E5%BF%83%E6%8A%80%E5%B7%A7")
• [8. 哲学反思------从 Skill 看 AI 的未来](#8. 哲学反思——从 Skill 看 AI 的未来 "#8-%E5%93%B2%E5%AD%A6%E5%8F%8D%E6%80%9D")
• [9. 参考资料------致敬先行者](#9. 参考资料——致敬先行者 "#9-%E5%8F%82%E8%80%83%E8%B5%84%E6%96%99")

---

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
推理引擎"] L2["🔍 Skill Matcher
技能匹配器"] L3["📄 Context Builder
上下文组装器"] end subgraph SKILL_REG ["📦 技能注册 --- Skill Registry"] R1["📦 Skill Registry
技能注册中心"] end subgraph MCP_LAYER ["🌐 MCP 协议层 --- Model Context Protocol"] M1["🌐 MCP Server"] M2["🔗 MCP Client"] M3["📋 Capability Discovery
能力发现"] end subgraph SKILL ["📦 Skill 层 --- Skill Packs"] S1["📄 SKILL.md
入口定义"] S2["📚 references/
参考文档"] S3["⚙️ scripts/
可执行脚本"] S4["🎨 assets/
模板资源"] end subgraph TOOL_DISP ["⚙️ 工具调度 --- Tool Dispatcher"] D1["⚙️ Tool Dispatcher
工具调度器"] 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 全景调用关系------从用户指令到工具执行的完整链路

图中关键路径解读：

1. 用户→IDE→LLM→Skill（主调用链 + 知识加载链）：用户的自然语言指令通过 IDE 传递给大模型，Skill Matcher 通过 Skill Registry 匹配对应的 Skill，Context Builder 按三级渐进机制加载 Skill 内容------先读元数据，再读 SKILL.md 正文，最后按需读取 references/scripts/assets
2. LLM→IDE→MCP→Tool（工具执行链）：LLM 生成 Tool Call 请求后交给 IDE，IDE 通过 MCP 协议进行能力发现和注册，Tool Dispatcher 将请求路由到具体的工具函数
3. 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
工作流指令"] K2["📚 references/
参考规范"] end subgraph EXEC ["⚡ 执行层 --- With What"] E1["🌐 MCP Server
能力注册"] E2["⚙️ Tool Use
函数调用"] 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
元数据 ~100 词"] == "始终在上下文" ==> B["📄 Level 2
SKILL.md 正文 <5K 词"] B == "按需读入上下文" ==> C["📚 Level 3
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 管理最佳实践

1. 命名空间 ：领域-功能 格式（code-review、commit-message、api-doc）
2. 单一职责：宁可多建几个小 Skill 也不要一个大而全
3. 松耦合：Skill 之间通过文件系统交互，不依赖内部 API
4. 版本控制：Skill 文件跟项目代码一起 Git 管理
5. 文档先行：先写 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 都是手写的。但可以预见的趋势是：

1. Skill 生成 Skill：让 AI 根据用户的使用模式，自动提炼出新的 Skill（Meta-Skill）
2. Skill 市场 ：像 npm/pip 一样的 Skill 包管理器，skill install code-review@v3
3. 自适应 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 .cursorrules Community 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 理念相通

---