一篇搞懂skill---深入理解 Claude Skills：从原理到项目实践

🔥个人主页：代码不加冰（欢迎来访）

🎬作者简介：java后端学习者

❄️个人专栏：LeetCode刷题日记，苍穹外卖日记，SSM框架深入，JavaWeb，

✨命运的结局尽可永在，不屈的挑战却不可须臾或缺！

前言：

大家好，我是代码不加冰，最近停更了一星期，主要忙于期末周，考完之后休息了一天，然后就是放假回家，今天刚刚到家，暑假也算是正式开始了，在此正式恢复更新，然后私信有没回的我会一个个回的，我们一起进步。

今天在看项目的时候，看到目录里面有一片专门的栏目，是五六个skill，在此之前，我只是在一些热门文章中看到过，并没有具体的去了解，只知道skill是给agent赋能，但是怎么写，怎么调用，可以说是完全不了解，因此，在这里详细讲解一下。这里以Claude skill为例。

摘要：

文章详细介绍了AI Agent中的Skill概念及其应用。Skill是一个包含SKILL.md文件的文件夹，用于指导Agent完成特定任务，支持脚本、参考文档等资源的按需加载。与系统提示词和MCP不同，Skill专注于具体任务的标准化执行，具有按需加载、节省token、团队知识沉淀等优势。文章还讲解了Skill的目录结构、编写要点（如description的清晰定义）、调用方式（自动触发或显式调用）以及实际应用场景（如文档生成、跨系统协作）。最后强调Skill的安全性、版本管理和描述清晰的重要性，建议从实际需求出发迭代优化Skill，以提升Agent的稳定性和效率。

一、什么是 Skill

1.1 一句话定义

Skill 是一个文件夹，里面至少包含一个 SKILL.md 文件，用来告诉 AI Agent**"在什么情况下、应该怎么完成某类特定任务"**。

它可以额外打包脚本（scripts/）、参考文档（references/）、模板资源（assets/）等，让 Agent 在需要时按需加载、按需执行。

用更形象的话说：Skill 就是把你反复向 AI 解释的"套路"------公司的品牌规范、某个业务的标准工作流、某种文件格式的操作细节------固化成一份可复用的说明书，让 Agent 每次遇到类似任务时自动照着做，而不需要你重新讲一遍。

1.2 Skill 的目录结构

一个典型的 Skill 长这样：

复制代码

text

my-skill/
├── SKILL.md          # 必需：YAML frontmatter + 指令说明
├── scripts/          # 可选：可执行的代码（Python/Shell 等）
├── references/       # 可选：Agent 按需加载的详细参考文档
└── assets/           # 可选：模板、图片等静态资源

SKILL.md：唯一必需文件，包含元数据（name、description）和具体指令。
scripts/：确定性强的操作用代码实现，比 Agent 现场"现编代码"更稳定、更省 token。
references/：不需要一次性全部塞进上下文的详细文档，Agent 判断需要时才读取。
assets/：Word 模板、Excel 模板、Logo 图片等在生成产物时要用到的静态文件。

1.3 Skill 与 Prompt、MCP 的关系

很多人会把 Skill、系统提示词（System Prompt）、MCP 三者混为一谈，实际上它们解决的是不同层面的问题：

机制	解决的问题	类比
系统提示词	定义 Agent 的基础人格与全局规则	员工手册的总则
MCP	让 Agent 能够"连接"外部系统、调用外部工具（读数据库、发邮件）	给员工配一部对讲机，能联系到其他部门
技能	教会 Agent 怎么把一件具体的事做对、做规范，赋能	具体岗位的 SOP（标准作业流程）操作手册

三者并不互斥，反而经常组合使用：MCP 负责"连得上"，Skill 负责"做得对" 。比如一个 Skill 完全可以在指令里写明"先调用某个 MCP 工具获取数据，再按下面的步骤处理"。

二、为什么要使用 Skill，有什么好处

2.1 解决的核心痛点

在 Skill 出现之前，想让 Agent 稳定地按照特定规范做事，通常只有两种笨办法：

每次对话都手动粘贴一大段说明------效率低，容易遗漏，团队协作时人人版本不一致。
把所有规范一股脑塞进系统提示词------上下文越堆越长，模型在无关任务上也要"背着"这些规则，浪费 token、稀释注意力，甚至互相冲突。

Skill 通过渐进式加载（Progressive Disclosure） 的设计解决了这个矛盾：

第一层 ：Agent 启动时只预加载所有已安装 Skill 的 name 和 description（非常轻量），据此判断"这个任务是否需要用到某个 Skill"。
第二层 ：一旦判定匹配，才把该 Skill 完整的 SKILL.md 内容读入上下文。
第三层 ：如果 SKILL.md 里引用了 references/ 下的文档或 scripts/ 下的代码，Agent 会按需进一步加载或执行，而不是一次性全部读入。

这意味着即便你给 Agent 装了几十个 Skill，只要它们没被触发，几乎不占用上下文空间------这是 Skill 相比塞进系统提示词最大的优势。

2.2 具体收益总结

一致性：同一件事无论谁来问、问多少次，Agent 都按同一套规范执行，避免"这次这么答、下次那么答"。
可复用 ：写一次，在 Claude.ai、Claude Code、Claude API、Claude Agent SDK 等多个产品面统一生效，无需重复适配。
省上下文/省成本：按需加载，未触发的 Skill 几乎零开销。
团队知识沉淀：把团队的领域知识、内部规范转成 Skill，等于让新成员（或者说"新 Agent 实例"）自动继承团队经验，不必每次口头传授。
代码而非纯语言描述：确定性强的步骤可以用脚本实现，比让模型"现场推理"更稳定、更快、更省 token。
开放标准，具备可移植性：Agent Skills 已经作为开放标准发布，理论上同一份 Skill 可以在不同的、支持该标准的 Agent 产品间迁移使用。

三、如何写一个 Skill

3.1 SKILL.md 的基本格式

一个最简单的 Skill 只需要两部分：YAML frontmatter + Markdown 指令正文。

复制代码

markdown

---
name: pdf-form-filler
description: 用于识别和填写 PDF 表单字段。当用户要求"填写PDF表单""提取PDF表单字段"或提到 PDF 表单相关操作时使用。
---

# PDF 表单填写技能

## 什么时候使用
当用户上传了一个包含可填写字段的 PDF，并要求填入具体内容时，使用本技能。

## 操作步骤
1. 使用 `scripts/extract_fields.py` 提取表单中的所有字段名与类型
2. 将提取结果与用户提供的数据一一对应
3. 使用 `scripts/fill_form.py` 完成填充并生成新文件
4. 检查是否有必填字段未被填写，如有需向用户确认

## 注意事项
- 不要臆造字段值，缺失信息必须先向用户确认
- 输出文件命名规则：原文件名 + "_filled.pdf"

3.2 编写要点与常见坑

Name 必须是 kebab-case，且要与文件夹名完全一致。 例如文件夹叫 pdf-form-filler，name 字段也必须写 pdf-form-filler，不能用下划线或驼峰。
description 是触发的关键，务必同时包含"做什么"和"什么时候用"。 这是最容易被忽视但影响最大的一环。Agent 完全是靠 description 来判断要不要加载这个 Skill 的，如果写得含糊（比如只写"处理PDF的技能"），触发就会不准，该激活时不激活，或者被无关任务误触发。
frontmatter 中不要使用尖括号等 XML 类符号。 因为 frontmatter 会直接进入 Agent 的系统提示词，出于安全考虑，这类符号在平台层面是被限制的，避免被用来做指令注入。
保持 SKILL.md 本身精简，细节下沉到 references/。 当指令内容变得庞大、或者存在"互斥场景"（比如 A 场景和 B 场景几乎不会同时出现）时，把各自的细节拆分成单独文件放进 references/，在正文里用链接引用即可，减少不必要的 token 消耗。
区分"该被执行的脚本"和"该被当参考读的文档"。 scripts/ 里的代码，Agent 应该是直接运行它，而不是读进上下文当文字理解；写指令时要明确说"运行 xxx.py"而不是"参考 xxx.py 中的逻辑"，避免 Agent 误把整段代码当文本消化，浪费上下文。
命名保留字限制。 Skill 名称中不能包含 "claude" 或 "anthropic" 字样，这两个是官方保留词，会被平台拒绝注册。
不要在 Skill 文件夹内放 README.md。面向 Agent 的说明一律写在 SKILL.md 或 references 里；如果要在 GitHub 上给人类读者看的说明，应放在仓库根目录，而不是 Skill 文件夹内部，避免和 SKILL.md 的定位混淆。

3.3 编写流程建议（从评估出发）

比较推荐的做法不是先拍脑袋写 Skill，而是：

先跑真实任务，找差距 ：让 Agent 在没有 Skill 的情况下完成一批有代表性的任务，观察它在哪些环节反复出错或缺乏必要上下文。
针对性补齐：把这些差距对应的知识、步骤、规范写成 Skill，而不是一上来就试图覆盖"所有可能情况"。
建立评估集（evals）：为 Skill 准备一批测试用例（输入 + 期望行为），验证 Skill 是否真的按预期触发、按预期执行。这一步在团队协作场景中尤其重要，可以在改动 Skill 后快速回归验证，防止"改好了 A 场景，却带崩了 B 场景"。
迭代：Skill 不是一次性交付物，应该像代码一样持续维护、根据实际使用反馈调整。

四、如何调用 Skill

调用方式因产品形态而异，核心逻辑都是自动触发为主，显式点名为辅。

4.1 自动触发

绝大多数场景下，你不需要"调用"Skill，只需要正常提需求，agent会根据任务内容与已安装 Skill 的 description 自动判断是否要用、用哪一个。比如你说"帮我把这份数据填进这个 PDF 表单里"，只要环境里装了对应的 PDF Skill，它会被自动激活，全程无需你手动指定。

4.2 在 Claude.ai 中使用

Anthropic 官方预置了一批常用 Skill（比如处理 PowerPoint、Excel、Word、PDF 等文档任务的 Skill），付费方案下是内置可用的，无需额外安装。
也可以在设置中上传自定义 Skill，之后同样按自动触发的方式生效。

4.3 在 Claude Code 中使用

通过插件市场安装：

复制代码

text

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

安装完成后运行 /reload-plugins 使其在当前会话生效。

Skill 也支持放在项目本地（比如 .claude/skills/ 目录）或个人全局目录下，前者仅在当前项目生效，后者跨项目通用。

除了自动触发，Claude Code 里还支持显式调用 ：直接输入斜杠命令，例如 /summarize-changes，或者在对话中直接点名------"用 PDF 技能提取这个文件里的表单字段"，等价于强制指定使用某个 Skill。

4.4 在 Claude API / Agent SDK 中使用

可以通过 Skills API 上传自定义 Skill，或直接使用 Anthropic 提供的预置 Skill（PowerPoint、Excel、Word、PDF 等）。
调用时通常需要配合"代码执行"（code execution）能力一起启用，因为很多 Skill 依赖运行 scripts/ 中的脚本来完成实际操作，比如生成一个真正的 .docx 文件。
这一套机制在 Claude API、Claude Platform on AWS、Microsoft Foundry（需 Hosted on Anthropic 部署）等多个平台上都可用。

4.5 一个简单的心智模型

可以把要不要调用 Skill这件事想成两种购物方式：

问题导向：你带着一个具体问题走进来（我要修橱柜），店员根据问题自动给你推荐合适的工具------这对应 Skill 的自动触发。
工具导向：你直接冲着某件工具去（给我拿电钻），然后再告诉店员你要用它做什么------这对应显式点名调用某个 Skill。

大多数 Skill 设计时会偏向其中一种模式，但两种调用方式在产品层面通常都支持。

五、在实际项目中怎么用

5.1 典型应用场景

结合官方及社区的实践经验，Skill 比较适合以下几类场景：

文档与产物生成类

把企业 VI 规范、PPT 排版规则、财务模型的配色规范（比如"蓝色代表输入项、黑色代表公式、绿色代表内部链接、红色代表外部链接"这类约定）固化为 Skill，配合内置质量检查清单，保证每次产出的 Word/PPT/Excel 都符合统一标准。

多步骤业务流程类

比如团队的 Sprint 规划流程、代码评审流程、事件复盘流程，写成 Skill 之后，Agent 就能按团队既定顺序一步步执行，而不是靠临场发挥。

跨系统协作类

与 MCP 结合使用：MCP 负责连接 Sentry、Jira、GitHub 等外部系统获取数据，Skill 负责教 Agent"拿到这些数据后该怎么分析、怎么处理、按什么顺序处理"。比如"根据 Sentry 报错信息自动分析并修复 GitHub PR 中的 bug"这样的复合工作流。

迭代优化类

有些任务"一次做不到位，需要反复打磨才能提升质量"，比如前端设计稿的视觉调整，这类场景下 Skill 里会包含"自我检查---修正"的循环步骤，而不是一次性输出。

5.2 与 MCP 集成的建议

如果团队已经有现成的 MCP Server（比如已经把内部系统接入了 MCP），Skill 可以视为"MCP 之上的知识层"------你已经做完了"连接"的硬活，Skill 负责把你熟悉的最佳实践、工作流程用自然语言 + 脚本的方式固化下来，让 Agent 稳定地按套路使用这些工具，而不是每次都要靠临场推理拼凑调用顺序。

5.3 落地时的注意事项

安全性：只使用可信来源的 Skill。 Skill 本质上是"指令 + 可执行代码"，如果来自不可信来源，恶意 Skill 完全可能诱导 Agent 执行超出其声明范围的操作，甚至造成数据泄露或未授权访问。建议只使用自己编写的、或者 Anthropic 官方发布的 Skill；如果一定要用第三方 Skill，务必先完整审查 SKILL.md、脚本、资源文件，留意是否有异常的网络请求、文件访问等和"技能描述"不符的行为。
数据合规：注意留存策略。 在 API 场景下，Skill 相关的定义与执行数据是按 Anthropic 标准数据留存策略处理的，如果你的业务对零数据留存（ZDR）有硬性要求，需要提前确认 Skill 功能是否满足你的合规要求。
版本管理：像对待代码一样对待 Skill。 建议纳入版本控制系统，配合 evals 测试集做回归验证，避免"改好一个场景、带崩另一个场景"。
命名与描述要经得起"多技能共存"的考验。 实际项目中往往会同时安装多个 Skill，如果两个 Skill 的 description 描述的触发场景有重叠或表述模糊，容易出现触发混乱。建议在设计阶段就假设"这个 Skill 会和其他 N 个 Skill 一起工作"，描述要尽量具体、边界清晰。

六、总结

Skill 本质上是一种**"把经验和规范代码化、结构化，并按需加载给 Agent"** 的机制。它之所以重要，是因为它解决了此前 Prompt 工程一直没解决好的矛盾：既要让 Agent 掌握大量专业知识，又不能让这些知识把上下文塞满、把成本推高。渐进式加载的设计，让 Skill 可以像一个个模块化的"专家插件"一样按需挂载。

如果用一句话总结实践建议： 从真实的失败案例出发写 Skill，把 description 写清楚，能用代码确定的步骤就不要交给模型现场推理，把它当代码一样做版本管理和测试。这样写出来的 Skill，才能在团队协作和长期迭代中真正发挥价值。

结语：

如果对你有帮助，请**点赞，关注，收藏，**你的支持就是我最大的鼓励！