“
Skill 不是什么高大上的黑盒，本质上就是一个普通文件夹：里面有一份必须的
SKILL.md（Markdown + YAML 头信息），可选地配上脚本、参考文档、模板资源。教你一次，以后 Claude 在合适的对话里自动按你的流程做事——少重复解释偏好、步骤和领域规矩。下文依据 Anthropic 官方指南 The Complete Guide to Building Skills for Claude 结构化整理，并补充中文场景示例与个人延伸思考（延伸部分会标明）。完整英文原版见项目仓库内同名 PDF。
一、为什么需要 Skill？两条路线先选边
1.1 人话版：从「每次重新教」到「装了一个常用动作包」
想象一下：你每个新项目都要跟同事重头讲一遍「我们代码风格怎样、周报格式怎样、提测前要检查哪几条」——累且容易漏。Skill 做的事，相当于把这套东西写成一份可复用的操作说明 + 触发条件，放进 Claude 的「能力」里。
指南里强调 Skill 特别适合可重复的工作流：按规格生成前端、按固定方法做调研、按团队版式写文档、编排多步任务等；且可与 Claude 内置能力（代码执行、写文档等）配合；若你已接 MCP，Skill 还能把「有工具」升级成**「知道怎样用好工具」**。
1.2 两条路径（指南原结构）
| 路线 | 适合谁 | 阅读重点 |
|---|---|---|
| 独立 Skill | 不依赖或少依赖外部 MCP | Fundamentals、Planning、测试与分发第 1–2 类场景 |
| Skill + MCP | 已有 MCP、希望用户「连上就会用」 | 「厨房与食谱」+ MCP 增强类（Category 3） |
官方预期：第一次做一个能跑的 Skill，用 skill-creator 辅助，大约 15–30 分钟量级的入门体验（以指南表述为准；实际因用例复杂度而异）。
二、Skill 是什么：文件夹里到底有什么
2.1 标准结构（必记）
your-skill-name/ # 文件夹名：kebab-case，见下文硬规则
├── SKILL.md # 必须：且文件名必须完全一致 SKILL.md（区分大小写）
├── scripts/ # 可选：Python、Bash 等可执行脚本
├── references/ # 可选：需要时再让模型按需读取的说明、API 细则、例子
└── assets/ # 可选：模板、字体、图标等静态资源
类比：SKILL.md 像目录 + 总菜谱；references/ 像附录手册（不让一顿饭的食材全堆在桌上，吃哪章翻哪章）；scripts/ 像料理机（确定性步骤交给程序跑）；assets/ 像预制碟形与摆盘素材。
2.2 三大设计原则（核心技术）
（1）渐进披露（Progressive Disclosure） —— 省 token、还能装得下大手册
指南明确三层：
| 层级 | 内容 | 何时进入模型上下文 |
|---|---|---|
| 第一层 | YAML frontmatter | 常驻系统侧「摘要」：让 Claude 知道什么时候该用这个 Skill，而不加载全文 |
| 第二层 | SKILL.md 正文 | 当判断与当前任务相关时加载：完整指令与流程 |
| 第三层 | 包内链接文件（references 等） | 按需再读：进一步细节 |
flowchart TB
yaml [YAML_frontmatter_always_hint]
body [SKILL_md_body_when_relevant]
refs [Linked_files_on_demand]
yaml --> body
body --> refs
（2）可组合（Composability）
多个 Skill 可同时启用——你的 Skill 不要假设「全宇宙只有我」，要避免与别的能力硬冲突。
（3）可移植（Portability）
同一份 Skill 在 Claude.ai、Claude Code、API 上行为一致（只要运行环境满足依赖；例如某些脚本要本地 Python）。
三、MCP 与 Skill：厨房与食谱
指南用了一个特别好记的比喻（以下为意译）：
| MCP | Skill | |
|---|---|---|
| 像什么 | 专业厨房：接水接电、设备与食材（工具与数据） | 菜谱：按什么顺序、用什么火候做成一道菜 |
| 提供什么 | 实时连服务、调工具 | 工作流、最佳实践、错误时怎么处理 |
| 一句话 | What Claude can do | How Claude should do it |
没有 Skill 时常见问题（指南列举方向）：用户连上 MCP 不知道下一步；支持工单问「怎样用你的集成」；每轮对话从零提示；同样能力每次说法不同结果飘；用户抱怨连接器，实际是缺工作流说明。
有 Skill 时：相关说法出现时工作流自动对齐；工具用法更一致；把「最佳实践」嵌进每次交互，降低学习成本。
四、规划与设计：先想 2–3 个真用例
4.1 好用例长什么样
指南用「Sprint 规划」类示例（以下为结构骨架，换成你的业务即可）：
- 触发：用户说「帮我规划本轮迭代」「在 Linear 里建 sprint 任务」等
- 步骤：拉状态 → 看速率/容量 → 排序 → 写回任务与标签
- 结果：一组已创建、已标注的任务
自检四问（指南原文意涵）：
- 用户到底想完成什么结果？
- 需要哪些多步操作？
- 用内置能力还是 MCP？
- 哪些领域知识/规矩要写进 Skill？
4.2 三类常见场景（指南归纳）
| Category | 用途 | 典型招术 |
|---|---|---|
| 1 文档与资产 | 稳定产出文档、幻灯、简单应用、设计稿等 | 嵌入版式/品牌规范、模板、交付前检查清单；常不需外连 |
| 2 工作流自动化 | 多步、可验证的流程（可跨 MCP） | 分步 + 校验门槛、模板、迭代润色回路 |
| 3 MCP 增强 | 教 Claude 如何用好某个 MCP | 编排多次调用顺序、领域经验、常见报错处理 |
中文示例 A（Category 1） ：
「把这篇技术草稿改成我们产品对外口吻，标题不超过 20 字，正文分「背景 / 方案 / 风险」三节，最后给一个 Checklist。」
中文示例 B（Category 2） ：
「每周五根据本周 Git 提交记录和会议纪要，生成研发周报 Markdown，并把我指定的指标表贴进第二节。」
中文示例 C（Category 3） ：
「用户说『用这个 CRM 新录入一条线索并安排回访』时，按我司 SOP：先查重 → 再创建 → 再建任务，任何一步失败给可复制的报错说明。」
4.3 成功标准：重要指标（指南原文立场）
官方明确：很多是志向性目标，带有一定主观；更完善度量仍在演进。可先从下列维度自评：
定量（示例，来自指南精神）
- 触发：对你设计的 10～20 条「应触发」问句，看是否多数能自动挂上 Skill（指南举例约 90% 量级作为努力方向）。
- 效率：同一任务对比开/关 Skill时的工具调用次数、总 token。指南举例：无 Skill 时多轮澄清、API 重试多；有 Skill 时期望更少来回、更少失败调用。
- 稳定性：关键工作流上 MCP 失败、重试是否可接受（甚至追求「当前工作流 0 次失败调用」作为努力方向，以日志为准）。
定性
- 用户不必反复提醒「下一步干啥」。
- 同样请求跑 3～5 遍，结构与质量稳定。
- 新用户尽量少上手说明能跑通。
五、技术硬规则：踩坑最多的地方
5.1 命名与文件
| 项 | 正确 | 错误 |
|---|---|---|
| 主文件 | 必须 SKILL.md | skill.md、SKILL.MD |
| Skill 文件夹名 | notion-project-setup | 空格、下划线、大驼峰 |
| 包内 | 不要放 README.md | 说明都应进 SKILL.md 或 references/ |
常见误解：GitHub 仓库根目录可以、也应该有给人看的 README；但打进压缩包上传的那份 Skill 目录里不要内嵌 README——避免与规范冲突。 （延伸思考） 团队可约定「仓库两层结构」：外层 README 给人类，内层 skills/xxx/ 严格符合规范。
5.2 YAML frontmatter：决定「会不会被想起来」
最低限度（指南）：
---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---
硬性要求摘要
name：kebab-case，与文件夹名一致；名称中不要出现保留词如把产品名蹭成官方品牌（指南：避免技能名含 claude / anthropic 作为不当占用）。description：必须同时说清楚「做什么」+「什么时候用」；少于 1024 字符；不要在里写 XML 尖括号<>（安全：会进系统提示）。- 可选：
license、compatibility（环境、网络、依赖说明）、metadata（作者、版本、关联 mcp-server 等）。
好 description vs 坏 description（指南思路 + 中文对照）
✅ 好：包含具体触发语、文件类型、业务动词。
- 英文例（指南）：上传
.fig、要 design-to-code handoff 等。 - 中文例：「处理飞书导出的 CSV 考勤，做异常打卡统计；当用户说考勤核对、异常打卡、导出报表时使用。」
❌ 坏：
- 「帮助做项目」——太泛，模型不知道何时加载。
- 只有「做什么」没有「用户会怎么说」。
- 堆内部实现术语、没有用户自然语言触发点。
5.3 正文 SKILL.md：推荐结构
指南建议包含：分步说明、示例对话、Troubleshooting。核心写法原则：
- 具体可执行：「运行
python scripts/validate.py --input {file}」优于「先验证一下数据」。 - 错误处理：MCP 断连、权限错误、典型返回码怎么处理。
- 大包小：细节放进
references/，正文只保留入口链接与何时去读。 - 控制体量：指南建议
SKILL.md尽量不超过约 5000 词（英文词数量级）；过长会拖慢、伤效果。
六、测试与迭代：别一上来就铺一百条用例
6.1 三种测法（由轻到重）
- Claude.ai 手动：最快，适合改 description、改步骤。
- Claude Code 脚本化：重复跑同一批Prompt，适合回归。
- API / 评估套件：规模化、自动化（指南提及 programmatic testing 方向）。
6.2 官方 Pro Tip：先死磕一个难任务
指南经验：让 Claude 在会话里先跑通一个够难的任务，把「胜出的做法」抽成 Skill，往往比泛泛铺用例更快拿到信号；再扩展覆盖。
6.3 三类测试（指南框架）
| 测试 | 目的 | 举例 |
|---|---|---|
| 触发 | 该加载时加载、不该加载时不加载 | 「创建 ProjectHub 项目」应触发；「旧金山天气」不应触发 |
| 功能 | 步骤对、API 成功、边界情况 | 建项目 + 5 条任务，属性与关联正确 |
| 对比基线 | 证明 Skill 真的省 | 对比轮次、token、失败调用（指南给了无 Skill vs 有 Skill 的示意数字） |
6.4 skill-creator：能做什么、不能做什么
- 能：从自然语言描述生成结构、
SKILL.md草案、触发语建议、审查常见问题、基于对话反馈迭代。 - 不能：替代你自动跑完整套量化评测（指南写明）。用法示例语气：「用 skill-creator 帮我为某某场景起草 Skill」。
6.5 迭代信号与对策
| 信号 | 可能问题 | 方向 |
|---|---|---|
| 欠触发 | description 太薄、缺关键词 | 补「用户怎么说」、技术名词 |
| 过触发 | 描述太宽 | 收窄场景、加负向说明（不要用在本 skill 的场景） |
| 执行飘 | 指令含糊、步骤没校验 | 写死检查点、必要时用脚本做确定性校验（指南：代码比纯自然语言可靠） |
七、分发与协作：2026 初指南里的路径（以官方更新为准）
个人（指南描述的常规路径）：下载 Skill 文件夹 → 按需 zip → Claude.ai：Settings → Capabilities → Skills 上传；或放入 Claude Code 的 skills 目录。
组织级（指南提及）：管理员可向工作区统一部署 Skill，并集中更新（指南中注明了大致时间节点；若你对外写稿，请再核一次 Anthropic 当前文档）。
开放标准：指南说明 Agent Skills 作为开放标准推进，与 MCP 类似强调可移植；具体兼容性可在 compatibility 里写明。
API 侧（概念级，细节以官方文档为准）：/v1/skills 管理；Messages API 通过 container.skills 等参数挂载；与 Agent SDK 结合；指南注明 API 使用 Skill 往往涉及 Code Execution Tool beta 等要求——上线前务必读最新 Skills API Quickstart。
推荐组合拳（指南） ：GitHub 公开放 Skill + 仓库 README 给人类看安装与截图；MCP 文档里链到 Skill，写清「连接器 + 技能」一起用的价值与最短上手路径。
定位话术：对外讲用户拿到的结果（「30 秒搭好工作区」），别上来就讲「我有个 YAML」（指南营销原则）。
八、五大模式 + 一句话场景（指南 Patterns 压缩版）
先选立场：Problem-first（用户说要做成什么）vs Tool-first（用户已经连了某某 MCP，要教「怎么用得专业」）——像去五金店，可以是「我要修柜子」或「我买了电钻该怎么用」。
| Pattern | 何时用 | 中文迷你场景 |
|---|---|---|
| 1 顺序编排 | 严格先后依赖 | 开户 → 绑支付方式 → 建订阅 → 发欢迎信 |
| 2 多 MCP 协同 | 跨系统 | Figma 导出 → Drive 归档 → Linear 建任务 → Slack 通知 |
| 3 迭代精炼 | 质量靠多轮抬高 | 拉数 → 出报告草稿 → scripts/check_report.py 检查 → 改到达标 |
| 4 上下文选工具 | 同类事不同工具 | 大文件走对象存储，协作文档走 Notion，代码走 Git |
| 5 领域规则 | 工具前有合规/业务闸门 | 支付前跑反洗钱与辖区规则，不过闸则建工单不进支付 |
九、排障速查（指南 Troubleshooting 精华）
| 现象 | 常见原因 | 处理 |
|---|---|---|
| 上传报找不到 SKILL.md | 文件名大小写 | 改为精确 SKILL.md |
| Invalid frontmatter | YAML 语法 | --- 成对、引号闭合 |
| Invalid skill name | 大写、空格 | 改 kebab-case |
| 从来不触发 | description 太泛或缺触发语 | 按「好描述」重写；问 Claude「何时会用某 skill」反查 |
| 乱触发 | 范围太大 | 收窄、加否定触发、写清边界 |
| MCP 失败 | 连接器本身问题 | 先无 Skill 单测 MCP；再查 tool 名大小写与文档 |
| 不按指令做 | 正文过长/要点埋没/措辞含糊 | 缩短、## Critical 提前、改成可执行检查项；关键步骤用脚本 |
| 越跑越慢/糊 | 上下文顶满 | SKILL.md 减肥、挪 references；减少同时启用 Skill 数量（指南提过 20～50 量级需警惕，视产品当前限制调整） |
指南提醒：对「多花时间认真做」这类话，写在用户 Prompt 里往往比在 SKILL.md 里更有效。
十、资源与自检清单（附录压缩）
值得收藏的官方入口（名称以指南为准）
- Skills 文档、MCP 文档、API Reference、Best Practices Guide
- 博客：Introducing Agent Skills、Equipping Agents for the Real World、Skills Explained、How to Create Skills、Claude Code 相关、Frontend Design via Skills 等
- 示例仓库：anthropics/skills；Partners Skills Directory
发布前自检（指南 Appendix A 精神）
- 2～3 个清晰用例、工具依赖想清楚
- 文件夹 kebab-case、
SKILL.md存在且命名正确 - YAML：
name/description（WHAT+WHEN）、无<> - 正文：步骤、示例、错误处理、链接到 references
- 触发：该触发 / 不该触发 都测过
- 功能与（如有）MCP 通过
- 上传包内无 README.md；对 GitHub 另写人类 README
十一、延伸思考（非 Anthropic 官方结论，仅供参考）
- Skill 与内部 wiki：Skill 是「模型可执行」的规范；wiki 给人看。两边应单一事实来源：改流程时记得同步 Skill，否则模型与文档会打架。
- 评测仍是「体感 + 小样」为主时：可做固定 20 条黄金 Prompt 周更回归，记录触发率、平均轮次、失败调用——比纯靠印象稳。
- 与 IDE Agent（如 Cursor 等）里的 Rules/Skills：理念相近但产品能力不同；不要假设同一套文件无改动能到处跑，迁移时对照各产品文档。
- 商业化想象空间：ISV 提供「MCP + 官方推荐 Skill」可降低集成支持成本；企业 IT 统一部署敏感流程 Skill，有利于审计与一致性。是否采纳取决于你们合规与产品策略。
十二、收尾
Skill 的本质是：用工程化文件树，把「什么时候启用 + 怎么做对」写给 Claude；配上 渐进披露，才能在能力变强时不把上下文塞爆。无论你只做独立自动化，还是做 MCP 生态，「有连接」和「会用连接」之间，差一层 Skill——这便是官方指南反复推进的一条主线。
有问题欢迎评论交流；产品行为与 API 以 Anthropic 最新文档为准，本文仅作导读。
