Skills 基本原理
Skill（技能） 是一份可复用的"操作手册"，本质上是一个带有元数据的 Markdown 文件。它告诉 Agent：在什么场景下、按什么步骤、用什么标准去完成一类任务。
所属专题：Skills 协议 (skills·01)
Skills 基本原理
一、什么是 Skill
Skill（技能） 是一份可复用的”操作手册”，本质上是一个带有元数据的 Markdown 文件。它告诉 Agent：在什么场景下、按什么步骤、用什么标准去完成一类任务。
可以把 Skill 理解为：
- Prompt 工程的模块化封装 —— 把经过验证的最佳实践沉淀成可复用单元
- Agent 的领域知识包 —— 让模型在特定场景下拥有专家级方法论
- 一份”随取随用”的说明书 —— 只有相关时才被加载，不污染主上下文
二、Skill 的核心结构
一个 Skill 就是一个带 YAML frontmatter 的 Markdown 文件：
---
name: skill-name
description: 简短一句话说明"什么时候用这个技能"，是触发匹配的关键
---
# 技能正文
## 步骤 1
...
## 步骤 2
...
## 红旗信号（Red Flags）
出现以下情况要停下重新评估：
- ...关键字段：
| 字段 | 作用 |
|---|---|
name | 技能唯一标识符（kebab-case） |
description | 触发描述，模型据此判断是否调用；必须写清”什么时候用” |
| 正文 | 具体的操作步骤、检查清单、原则、示例 |
三、渐进式披露机制（Progressive Disclosure）
这是 Skills 设计中最核心的思想：让 Agent 知道”有什么”，但只在需要时才知道”怎么用”。
三层加载模型
第 1 层：仅加载 name + description（始终在上下文中，几十字符）
↓ 模型判断"这个 skill 可能相关"
第 2 层：通过 Skill 工具调用，加载完整正文
↓ 正文中可能引用 references/xxx.md
第 3 层：按需读取 references 里的深度文档第一层：元数据层（关键理解）
加载内容： 只有 name + description（YAML frontmatter 的核心字段）
特点：
- 始终常驻上下文 —— 每次对话开始就注入到 system prompt
- 极轻量 —— 一个 skill 通常几十到一两百字符
- 只用于”路由判断” —— 模型据此决定”这个 skill 相不相关”
- 正文完全不加载 —— 具体步骤、示例、检查清单都还在磁盘上
类比理解
第一层就像是图书馆的索引卡：
- 卡片上只有书名 + 一句话摘要
- 你翻卡片决定要不要去书架取书
- 真正的内容在书里，不占你桌面空间
三层完整对照
| 层级 | 加载内容 | 加载时机 | 类比 |
|---|---|---|---|
| L1 元数据 | name + description | 会话开始，常驻 | 索引卡 |
| L2 主体 | SKILL.md 正文 | 判断相关后，Skill 工具调用时 | 从书架取书 |
| L3 引用 | references/*.md、scripts/ 等 | 正文中提到时，按需 Read | 翻到附录章节 |
为什么这么设计？
如果没有分层：
- 100 个 skill × 每个 2000 字 = 20 万字全塞进上下文 → 爆炸
- 且大部分内容当前任务用不上 → 浪费 token、干扰注意力
有了分层：
- 100 个 skill 的元数据 ≈ 几千字，可接受
- 只有真正相关的 1-2 个才展开正文
- skill 数量可以无限扩展，不受上下文窗口限制
同源设计思想
这个设计模式在 Agent 系统里叫 Progressive Disclosure（渐进式披露）， 也是 MCP 工具发现、Anthropic ToolSearch 等机制的共同思想 —— 用”发现层 + 加载层”两段式，把无限的能力池装进有限的上下文窗口。
四、Skill 的触发机制
Agent 每次响应前，会扫描所有 skill 的 description，判断是否有匹配。触发路径有两条：
- 隐式触发 —— 模型根据用户请求 + skill description 自动匹配
- 例：用户说”帮我 debug 这个错误” → 触发
systematic-debugging
- 例：用户说”帮我 debug 这个错误” → 触发
- 显式触发 —— 用户用
/skill-name直接调用- 例：用户输入
/brainstorming→ 强制加载
- 例：用户输入
Description 写作要点：
- 写”什么时候用”而不是”这个 skill 是什么”
- 例：❌ “TDD 方法论” ✅ “Use when implementing any feature or bugfix, before writing implementation code”
五、Skill 的存放位置
| 层级 | 路径 | 作用域 |
|---|---|---|
| 用户级 | ~/.claude/skills/ | 所有项目共享 |
| 项目级 | .claude/skills/ | 当前项目独有 |
| 插件级 | 通过 plugin 分发 | 命名空间plugin:skill |
目录结构示例：
.claude/skills/my-skill/
├── SKILL.md # 主入口（必需）
├── references/ # 深度文档，按需加载
│ ├── advanced.md
│ └── examples.md
└── scripts/ # 可选：辅助脚本
└── check.sh六、Skill vs 其他机制
| 机制 | 用途 | 加载时机 |
|---|---|---|
| Skill | 可复用方法论、操作流程 | 按需加载 |
| Memory (CLAUDE.md) | 项目常识、用户偏好 | 每次会话必载 |
| Slash Command | 快捷指令入口 | 用户触发 |
| Subagent | 独立上下文执行子任务 | 显式派发 |
| Hook | 事件驱动的自动化 | 系统触发 |
关键区别：
- Memory 是”永远记住的事实”，Skill 是”需要时查阅的手册”
- Slash Command 常常就是 Skill 的触发入口
七、写好一个 Skill 的原则
1. 单一职责
一个 skill 只解决一类问题，不要做”万金油”。
2. Description 精准
决定它能否被正确触发的唯一线索。写清楚：
- 何时用（触发条件）
- 不适用于什么（排除条件）
3. 结构化步骤
- 用 checklist、编号步骤，方便模型逐项跟进
- 每个步骤有明确的验证标准
4. 提供”红旗信号”（Red Flags）
列出常见的走偏迹象，让模型能自检：
- “如果你想’先探索代码再决定’——停，先调用 skill”
5. 给出正反例
- ✅ 正确用法
- ❌ 常见错误
- 让模型学到边界
6. 引用 references 拆分复杂度
主 SKILL.md 保持精简（<200 行），深度内容放 references，按需加载。
八、Skill 的执行生命周期
用户请求
↓
系统注入 skill 列表（name + description）
↓
模型判断相关性
↓
调用 Skill 工具 → 加载正文
↓
按 skill 指引执行（可能派生 TodoList、Subagent、其他工具）
↓
必要时读取 references/*
↓
完成任务九、Skill 与 Agent 系统设计的关系
Skill 是 将”专家经验”注入 LLM 的最轻量方式：
- 无需 fine-tuning
- 无需修改 Agent 主逻辑
- 靠”文档 + 触发机制”就能让 Agent 掌握新领域方法论
它体现了当前 Agent 设计的重要理念：
模型是通用的，能力是插拔的。
Skill 系统让 Agent 从”什么都会一点”进化为”随时召唤对应领域专家”。
十、典型 Skill 示例场景
| Skill | 触发场景 | 核心作用 |
|---|---|---|
brainstorming | 用户想”做一个新功能” | 强制先探索需求，避免直接写代码 |
systematic-debugging | 出现 bug、测试失败 | 引导按科学方法排查根因 |
test-driven-development | 要实现新功能 | 强制先写测试再写实现 |
deep-research | 需要多源事实核查 | 编排搜索 → 验证 → 综合流程 |
code-review | 提交前审查代码 | 按 checklist 逐项检查 |
十一、Skills vs MCP vs Function Calling
三者常被混为一谈，其实处在完全不同的抽象层，是互补关系而非竞争关系。
1. 本质定位对比
| 维度 | Function Calling | MCP | Skills |
|---|---|---|---|
| 本质 | LLM 的底层能力 | 工具分发的协议标准 | 方法论的封装 |
| 回答的问题 | ”怎么调工具" | "工具从哪来" | "什么时候、怎么做” |
| 提供什么 | 结构化输出机制 | 工具/资源/prompt 的接入 | 步骤、原则、检查清单 |
| 类比 | CPU 指令集 | USB 接口标准 | 操作手册 |
| 谁定义 | 模型厂商（OpenAI/Anthropic） | Anthropic 主导的开放协议 | 用户/团队自定义 |
2. 通俗类比：修车厂
想象 Agent 是一个修车师傅：
- Function Calling = 师傅的手，能拿起工具、拧螺丝 → 底层执行能力
- MCP = 车间墙上的工具挂架标准，任何品牌的扳手都能挂上去 → 工具接入协议
- Skills = 师傅头脑里的维修手册：“换刹车片先顶车、再拆轮、检查油管…” → 方法论
三者缺一不可：
- 只有手没有工具 → 干不了活
- 只有工具没有手册 → 不知道怎么修
- 只有手册没有工具 → 空谈理论
3. 技术层次图
┌─────────────────────────────────────────┐
│ 用户请求："帮我查数据库表结构" │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ Skills 层（方法论） │
│ → 触发 "database-inspection" skill │
│ → 告诉模型："先看 schema，再看索引..." │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ MCP 层（工具供给） │
│ → postgres-mcp-server 提供了 query 工具 │
└─────────────────────────────────────────┘
↓
┌─────────────────────────────────────────┐
│ Function Calling 层（执行机制） │
│ → 模型输出：{tool: "query", args: {...}}│
│ → 系统执行、返回结果 │
└─────────────────────────────────────────┘4. 关键差别详解
Function Calling — 能力原语
- 是什么：模型能输出结构化 JSON 来”调用函数”的能力
- 形式：
{"name": "get_weather", "arguments": {"city": "北京"}} - 谁提供：模型本身（训练时具备）
- 局限：每个工具需要手动注册到 LLM 请求里，没有标准分发方式
MCP — 工具的”USB 标准”
- 是什么：一套协议，让工具/资源/prompt 能像插 U 盘一样接入任何 LLM 客户端
- 解决的痛点：以前每接一个新工具都要写胶水代码，MCP 让工具生态可以标准化流通
- 提供三类东西：
- Tools —— 可执行的函数（最终变成 function calling）
- Resources —— 可读取的数据（文件、DB、API）
- Prompts —— 预设的 prompt 模板
- 关键：MCP 不改变模型如何调用工具，只改变工具如何被发现和接入
Skills — 方法论包
- 是什么：告诉模型”面对某类任务，按这个流程/原则去做”
- 形式：Markdown 文档 + YAML 元数据
- 不是工具：本身不执行任何操作，只是”指令 + 知识”
- 触发方式：description 匹配（渐进式披露）
- 典型内容：步骤清单、红旗信号、正反例、验证标准
5. 能力对比矩阵
| 能力 | Function Calling | MCP | Skills |
|---|---|---|---|
| 能执行代码/操作？ | ✅ | ✅（通过 Tools） | ❌ |
| 能提供数据？ | ❌ | ✅（通过 Resources） | ❌ |
| 能引导思考流程？ | ❌ | 部分（Prompts） | ✅ |
| 跨模型通用？ | 各家 API 略不同 | ✅ 协议中立 | ✅ 纯文本 |
| 需要外部进程？ | ❌ | ✅（MCP server） | ❌ |
| 可动态发现？ | ❌ 需预注册 | ✅ | ✅ |
| 谁写得起？ | 开发者 | 开发者 | 任何人（写 markdown） |
6. 典型协作场景
场景：用户说”审查这个 PR 的安全问题”
-
Skill 触发 ——
security-reviewskill 被激活“先扫依赖漏洞 → 再查认证/授权 → 最后检查敏感数据泄露”
-
Skill 指引调用 MCP 工具 —— skill 正文里说”用
github-mcp拉取 diff，用snyk-mcp扫漏洞” -
MCP 工具通过 Function Calling 执行 —— 模型输出
{"tool": "github.get_pr_diff", ...}，系统执行 -
结果回流 —— Function Calling 拿到结果 → MCP 转换 → Skill 指导下一步
三者关系：Skills 是大脑（策略），MCP 是神经系统（接入），Function Calling 是肌肉（动作）。
7. 一句话记忆
- Function Calling：模型怎么动手 —— 执行机制
- MCP：工具从哪来 —— 接入协议
- Skills：任务该怎么做 —— 方法论
三者组合，才是完整的 Agent 能力栈。
参考
- 官方规范：Anthropic Skills / Claude Code Skills
- 本仓库示例：
~/.claude/skills/、~/.claude/plugins/ - 相关概念：[[MCP]] 提供工具接入，Skills 提供方法论接入，二者互补