🎯 Skills是什么？

随着 AI 应用从简单的"单轮问答"走向复杂的"自动化工作流"，Skills 已经成为大模型应用架构中绕不开的工程概念。

更合理的工程做法，是把每一项专项能力分别写成独立的 SKILL.md：

• 代码审查标准
• 慢查询排查流程
• 报告生成规范

元数据常驻上下文，正文按需加载。新人能读懂，换项目能复用，Agent 按需激活执行，互不干扰。

🧠 核心定义

Skill 是一个用自然语言定义的、具有特定领域上下文的逻辑指令集，本质上是通过延迟加载优化 Token 消耗的 sub-agent。

在团队协作中，很多"隐性知识"都在老员工脑子里，比如代码规范、排查流程、Review 标准。

Skills 的核心价值在于：把这些隐性规则变成显性的文档（SOP），让 AI 能够自主阅读、理解并执行。

与传统的硬编码逻辑不同，Skill 不强制规定每一步的代码逻辑，而是用自然语言将决策权下放给模型。

模型通过 load_skill() 动态加载 SKILL.md 后，将其中定义的规则、流程和约束实时注入到推理上下文中，指导后续的工具调用和决策。这既保留了 Agent 处理不确定性的优势，又避免了纯代码编排的僵化。

🔧 关键机制

延迟加载（Lazy Loading）

• 元数据保持简短，常驻上下文
• 正文仅在触发时动态注入，避免挤占 Token

动态上下文注入

• 不同于静态文档的"阅读"，Skills 是将规则实时注入推理上下文
• 直接影响模型决策，而非仅作为参考

当你或 Claude 调用一个 skill 时，呈现的 SKILL.md 内容作为单个消息进入对话，并在会话的其余部分保持在那里。Claude Code 不会在后续轮次重新读取 skill 文件，因此将应该在整个任务中应用的指导写成常设说明，而不是一次性步骤。

自动压缩 在令牌预算内转发调用的 skills。当对话被总结以释放上下文时，Claude Code 在总结后重新附加每个 skill 的最新调用，保留前 5,000 个token。重新附加的 skills 共享 25,000 个token的组合预算。Claude Code 从最近调用的 skill 开始填充此预算，因此如果你在一个会话中调用了许多 skills，较旧的 skills 可能会在压缩后完全删除。

如果一个 skill 似乎在第一个响应后停止影响行为，内容通常仍然存在，模型正在选择其他工具或方法。加强 skill 的 description 和说明，以便模型继续偏好它，或使用 hooks 来确定性地强制行为。如果 skill 很大或你在它之后调用了其他几个，在压缩后重新调用它以恢复完整内容。

🚫 为什么不是"基于 Function Calling 封装"？

这个表述容易让人误以为 Skill 是某种 Function Calling 的语法糖。实际上，Skill 的核心机制是上下文注入——Agent 读取 Markdown 文档，把其中的规则和流程纳入推理上下文。

Function Calling 只是 Agent 执行某些动作时可能用到的底层手段，不是 Skills 本身的定义层。

注意：load_skill() 是对"Agent 读取并激活 SKILL.md"这一过程的概念性描述，不同工具的实际触发方式会有差异。

🔍 Skills与相关概念的区别

📝 Skills vs Prompt

提示词工程更像是“这一次对话里，我把要求写清楚”。Skill更像是“把这套要求、流程、模板，甚至脚本，打包成一个可复用的能力”。

• 复用性不一样
  • 提示词工程通常是一次性的，或者用户得反复复制粘贴同一套 prompt。
  • Skill 是可复用的，后面再遇到类似任务，可以直接按这套固定方法做
• 封装的内容不一样
  • 普通 prompt 主要是文字指令。
  • Skill 除了指令，还可以带参数、条件、循环等复杂逻辑。 一句话总结：Prompt 是用户即时表达意图的载体；Skills 是包含元数据（何时使用）+ 正文（如何执行）的完整方案，通过 load_skill() 机制按需加载到上下文。

🌐 Skills vs MCP

这是最容易产生误解的地方。

• MCP 解决的是连通性：它像 USB-C，让 AI 能以统一格式读文件、查数据库。

• Skills 解决的是编排逻辑：它像一份说明书，告诉 AI 如何执行复杂任务流。这些任务完全可以包括调用多个 MCP 工具。

两者关系：它们不是竞争关系，而是解决不同层面的问题。MCP 负责把外部系统接入，Skills 负责决定什么时候用、怎么组合这些能力。一个高级 Skill 的底层往往调用多个 MCP 工具。

• 当你的问题核心是“这一类任务每次都要按同一套方法做”。比如固定格式周报、PRD 摘要模板。这类场景重点是流程复用、输出一致、少重复解释，更适合 Skill。Skills 适合可重复任务、团队规范、模板/checklist、多步骤工作流
• 当你的问题核心是“模型需要访问某个外部系统，不连上就做不了”。比如要查 Notion、日历、数据库、GitHub、Figma、内部工具，或者要调用搜索、执行器、业务 API。这类场景重点是连接能力和工具能力，更适合 MCP。MCP 官方定义里明确把它定位成连接外部数据源、工具和工作流的标准接口。

⚡ Function Calling vs Skills

Skills 没有创造新能力，而是通过自然语言文档将能力组织成更易用的形式。

Agent 读取 SKILL.md，将规则和流程注入推理上下文。根据上下文指导，Agent 可能通过 Function Calling 执行脚本、读取资源或调用 MCP 工具。

🎨 四层关系总结

层级关系：Function Calling 是地基 → Prompt 表达意图 → MCP 负责连通外部系统 → Skills 负责编排复杂任务流。

一句话总结：Prompt 承载意图，Function Calling 实现交互，MCP 负责连通外部系统，Skills 负责编排复杂任务流——从"说什么"到"怎么做"再到"聪明地做"。

🧪 Skills示例

📂 Skill的目录结构

从结构上看，Skill 核心就是一个 SKILL.md 文件，包含元数据（描述什么时候用）和正文（具体的执行 SOP）。

设计亮点是渐进式披露：元数据常驻上下文，AI 知道有哪些技能可用；正文按需加载，只有触发时才读取。

复杂点的 Skill 还会有附加的资源目录、脚本和参考文档：

1
2
3
4
5

skill-name/
├── SKILL.md              # 必需：元数据（何时使用）+ 正文（指令、流程、示例）
├── scripts/              # 可选：可执行脚本（Python/Bash），按需调用
├── references/           # 可选：参考文档，按需读取
└── assets/               # 可选：模板、图片等资源

Skills 可以在其目录中包含多个文件。这使 SKILL.md 专注于要点，同时让 Claude 仅在需要时访问详细的参考资料。大型参考文档、API 规范或示例集合不需要在每次 skill 运行时加载到上下文中。

1
2
3
4
5
6

my-skill/
├── SKILL.md (required - overview and navigation)
├── reference.md (detailed API docs - loaded when needed)
├── examples.md (usage examples - loaded when needed)
└── scripts/
    └── helper.py (utility script - executed, not loaded)

从 SKILL.md 中引用支持文件，以便 Claude 知道每个文件包含什么以及何时加载它：

1
2
3
4

## Additional resources

- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

将 SKILL.md 保持在 500 行以下。将详细的参考资料移到单独的文件中。

📄 SKILL.md示例结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# code-review-expert

## Meta
- name: code-review-expert
- description: 资深工程师视角的结构化代码审查
- triggers: 当需要审查代码质量时激活

## Capabilities
1. 架构设计审查
2. SOLID 原则合规性检查
3. 安全性风险扫描
4. 性能问题识别
5. 错误处理完整性
6. 边界条件覆盖

## Review Framework
1. 接收代码片段或文件路径
2. 逐维度分析（见 Capabilities）
3. 输出结构化审查报告
4. 针对每项问题提供修复建议

## Output Format
- 问题编号与严重程度
- 问题描述与代码位置
- 修复建议与参考规范

💼 项目实战场景

在工程实践中，Skills 主要用于固化工程标准：

使用 Skills 的好处：AI 在执行任务时，不再是"随缘发挥"，而是严格执行团队标准，保持质量一致性。

📚 推荐Skills资源

• skills.sh：查找热门和所需的 Skills
• Superpowers：内置多种开箱即用的开发 Skills
• Claude Code 内置 Skills：包括 /simplify（审查修复）、/batch（批量修改）、/debug（排查问题）等

🛠️ 如何开发一个Skill

📑 Skill 内容的类型

Skill 文件可以包含任何说明，但思考用户想如何调用它们有助于指导要包含的内容：

参考内容 添加 Claude 应用于当前工作的知识。约定、模式、风格指南、领域知识。此内容内联运行，以便 Claude 可以将其与对话上下文一起使用。

1
2
3
4
5
6
7
8
9

---
name: api-conventions
description: API design patterns for this codebase
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

任务内容 为 Claude 提供特定操作的分步说明，如部署、提交或代码生成。这些通常是想使用 /skill-name 直接调用的操作，而不是让 Claude 决定何时运行它们。添加 disable-model-invocation: true 以防止 Claude 自动触发它。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---

Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment target

SKILL.md 可以包含任何内容，但思考用户想如何调用该 skill（由你、由 Claude 或两者）以及你想在哪里运行它（内联或在 subagent 中）有助于指导要包含的内容。对于复杂的 skills，你也可以 添加支持文件 以保持主 skill 的专注。

保持主体本身简洁。一旦 skill 加载，其内容在整个会话中保持在上下文中，因此每一行都是一个重复的令牌成本。说明要做什么而不是叙述如何或为什么，并应用与 CLAUDE.md 内容 相同的简洁性测试。

⚙️ Skill的相关配置

除了 markdown 内容外，可以使用 SKILL.md 文件顶部 --- 标记之间的 YAML frontmatter 字段来配置 skill 行为：

1
2
3
4
5
6
7
8

---
name: my-skill
description: What this skill does
disable-model-invocation: true
allowed-tools: Read Grep
---

Your skill instructions here...

所有字段都是可选的。建议使用 description ，以便 Claude 知道何时使用该 skill。

🔤 可用的字符串替换

Skills 支持 skill 内容中动态值的字符串替换：

${CLAUDE_PROJECT_DIR} 替换需要 Claude Code v2.1.196 或更高版本。它适用于 skill 主体和 allowed-tools frontmatter，因此权限规则如 Bash(${CLAUDE_PROJECT_DIR}/scripts/lint.sh *) 解析为 skill 主体使用的相同路径。

索引参数使用 shell 风格的引用，因此用引号包装多词值以将其作为单个参数传递。例如， /my-skill "hello world" second 使 $0 扩展为 hello world ， $1 扩展为 second 。 $ARGUMENTS 占位符始终扩展为完整的参数字符串，如输入的那样。

要包含文字 $ 在数字、 ARGUMENTS 或声明的参数名称之前，例如散文中的 $1.00 ，用反斜杠转义它： \$1.00 。反斜杠在任何其他 $ 之前保持不变。只有直接在令牌之前的单个反斜杠才能转义它。双反斜杠（如 \\$1 ）保留两个反斜杠， $1 仍然扩展为参数值。

使用替换的示例：

1
2
3
4
5
6
7
8

---
name: session-logger
description: Log activity for this session
---

Log the following to logs/${CLAUDE_SESSION_ID}.log:

$ARGUMENTS

👥 配置skill的调用方

默认情况下，用户和 Claude 都可以调用任何 skill。你可以输入 /skill-name 直接调用它，Claude 可以在与你的对话相关时自动加载它。两个 frontmatter 字段让你限制这一点：

• disable-model-invocation: true ：只有你可以调用该 skill。用于有副作用的工作流或你想控制时间的工作流，如 /commit 、 /deploy 或 /send-slack-message 。你不希望 Claude 因为你的代码看起来准备好了就决定部署。
• user-invocable: false ：只有 Claude 可以调用该 skill。用于不可作为命令操作的背景知识。 legacy-system-context skill 解释了旧系统的工作原理。Claude 在相关时应该知道这一点，但 /legacy-system-context 对用户来说不是一个有意义的操作。

此示例创建一个只有你可以触发的部署 skill。 disable-model-invocation: true 字段防止 Claude 自动运行它：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

Deploy $ARGUMENTS to production:

1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

以下是两个字段如何影响调用和上下文加载：

在常规会话中，skill 描述被加载到上下文中，以便 Claude 知道什么可用，但完整 skill 内容仅在调用时加载。 预加载 skills 的 Subagents 的工作方式不同：完整 skill 内容在启动时注入。

🔐 配置 skill 的工具集

allowed-tools 字段在 skill 处于活动状态时授予对列出的工具的权限，因此 Claude 可以使用它们而无需提示你获得批准。它不限制哪些工具可用：每个工具仍然可调用，你的 权限设置 仍然管理不在列表中的工具。

对于检入项目的 .claude/skills/ 目录的 skills， allowed-tools 在你接受该文件夹的工作区信任对话后生效，与 .claude/settings.json 中的权限规则相同。在信任存储库之前查看项目 skills，因为 skill 可以授予自己广泛的工具访问权限。

此 skill 让 Claude 在你调用它时运行 git 命令而无需每次使用批准：

1
2
3
4
5
6

---
name: commit
description: Stage and commit the current changes
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

要在 skill 处于活动状态时从 Claude 的可用工具池中移除某些工具，请在 skill 的 frontmatter 中的 disallowed-tools 中列出它们。当你发送下一条消息时，限制会清除。要在所有 skills 和提示中阻止工具，请在你的 权限设置 中添加拒绝规则。

📨 将参数传递给 skills

用户和 Claude 都可以在调用 skill 时传递参数。参数可通过 $ARGUMENTS 占位符获得。

此 skill 按编号修复 GitHub 问题。 $ARGUMENTS 占位符被替换为 skill 名称后面的任何内容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit

当用户运行 /fix-issue 123 时，Claude 收到”Fix GitHub issue 123 following our coding standards…”

如果用户使用参数调用 skill 但 skill 不包含 $ARGUMENTS ，Claude Code 会将 ARGUMENTS: <your input> 追加到 skill 内容的末尾，以便 Claude 仍然看到用户输入的内容。

用户也可以在一条消息的开头堆叠多个 skills。从 v2.1.199 开始，输入 /code-review /fix-issue 123 会加载两个 skills 并将尾部文本 123 作为 $ARGUMENTS 传递给每个 skills。在早期版本中，只有第一个 skill 加载并接收 /fix-issue 123 作为文字参数文本。

Claude Code 扩展第一个 skill 加上最多五个堆叠在其后的 skills。扩展在第一个不是内联用户可调用 skill 的令牌处停止，因此作为 分叉 subagent 运行的 skill 或其参数本身可能以斜杠命令开头的 skill（如 /loop ）也会在那里结束；该令牌及其后的所有内容成为每个扩展 skill 的参数文本。

要按位置访问单个参数，使用 $ARGUMENTS[N] 或较短的 $N ：

1
2
3
4
5
6
7

---
name: migrate-component
description: Migrate a component from one framework to another
---

Migrate the $ARGUMENTS[0] component from $ARGUMENTS[1] to $ARGUMENTS[2].
Preserve all existing behavior and tests.

运行 /migrate-component SearchBar React Vue 会将 $ARGUMENTS[0] 替换为 SearchBar ， $ARGUMENTS[1] 替换为 React ， $ARGUMENTS[2] 替换为 Vue 。使用 $N 简写的相同 skill：

1
2
3
4
5
6
7

---
name: migrate-component
description: Migrate a component from one framework to another
---

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

🔀 在 subagent 中运行 skills

当你想让 skill 在隔离中运行时，在你的 frontmatter 中添加 context: fork 。skill 内容变成驱动 subagent 的提示。它将无法访问你的对话历史。

context: fork 仅对具有明确说明的 skills 有意义。如果你的 skill 包含”使用这些 API 约定”之类的指南而没有任务，subagent 会收到指南但没有可操作的提示，并返回而没有有意义的输出。

Skills 和 subagents 以两个方向协同工作：

使用 context: fork ，你在你的 skill 中编写任务并选择一个代理类型来执行它。内置的 Explore 和 Plan 代理 跳过 CLAUDE.md 和 git 状态 以保持其上下文较小，因此使用 agent: Explore 的分叉 skill 仅看到 SKILL.md 内容和代理自己的系统提示。对于反向情况，其中你定义使用 skills 作为参考资料的自定义 subagent，请参阅 Subagents 。

此 skill 在分叉的 Explore 代理中运行研究。skill 内容变成任务，代理提供针对代码库探索优化的只读工具：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

当此 skill 运行时：

1. 创建一个新的隔离上下文
2. Subagent 接收 skill 内容作为其提示（“Research $ARGUMENTS thoroughly…”）
3. agent 字段确定执行环境（模型、工具和权限）
4. 结果被总结并返回到你的主对话

agent 字段指定要使用的 subagent 配置。选项包括内置代理（ Explore 、 Plan 、 general-purpose ）或来自 .claude/agents/ 的任何自定义 subagent。如果省略，使用 general-purpose 。

📌 总结

Skills 的本质：用自然语言定义的、具有特定领域上下文的逻辑指令集，通过延迟加载优化 Token 消耗，本质上是 sub-agent。

Skills 的价值：

• 模块化：每个 Skill 专注一项能力，互不干扰
• 可复用：换项目时直接迁移，新人易读懂
• 按需加载：元数据常驻，正文按需注入，不挤占上下文

Skills 与其他组件的关系：

• Prompt 承载意图
• Function Calling 实现交互
• MCP 负责连通外部系统
• Skills 负责编排复杂任务流

适用场景：当用户的 Agent 工作流节点增多、审查标准变复杂、团队需要协作时，Skills 是将"隐性知识"显性化、工程化的最佳实践。