Claude的私人厨房：从文件夹炼出定制智慧的奇幻食谱

🌟 序章：学徒的烦恼与食谱的诞生

我这些年帮团队折腾AI，最头疼的一件事就是重复劳动。每次要Claude做前端设计、规划Sprint或者审代码，都得从头解释一遍流程、风格、注意事项。像请了个天赋异禀却每天失忆的学徒。说白了，Claude聪明是聪明，可它不知道你团队的“家法”。

直到我读到这份《构建Claude技能完全指南》，才像忽然开了窍。技能不是什么高深黑科技，就是一个普普通通的文件夹，里面装着“食谱”。一次写好，终身受用。Claude再遇到类似活儿，直接翻食谱，按部就班。省下的时间，够你多喝几杯咖啡。

指南开篇就点明：技能是一套打包好的指令，专门教Claude处理特定任务或工作流。适合那些重复出现的场景——从规格生成前端界面、按固定方法做研究、输出符合团队风格的文档，到编排多步流程。它跟Claude自带的代码执行、文档创建天生合得来。对做MCP整合的人来说，更是把“能用工具”升级成“会用工具”的关键一层。

想象一下，你面前有两样东西：MCP是专业厨房，里面刀具、食材、炉灶一应俱全；技能则是食谱本，告诉你怎么把这些东西变成一桌像样的菜。没了食谱，客人点菜你只能干瞪眼；有了食谱，学徒也能端出稳定水准的菜。

🧱 筑基三层：渐进披露的聪明设计

技能的文件夹结构简单得近乎朴素，却藏着大学问。必备文件只有一个——SKILL.md，Markdown格式，前面还带YAML前言。scripts文件夹放可执行脚本，references放需要时才翻的文档，assets放模板、字体这些输出要用到的东西。

核心原则叫渐进披露。分三层，像洋葱一样，一层一层剥，不浪费精力。

第一层是YAML前言，永远躺在Claude的系统提示里。它只说最关键的事：这个技能叫什么、什么时候该用。Claude一看就知道“哦，这个活儿我有现成食谱”，不会把整本食谱一股脑塞进上下文吃掉token。

第二层是SKILL.md正文。Claude判断当前任务跟这个技能相关了，才会把完整指示加载进来。里面写着步骤、例子、排错。

第三层是关联文件。需要查API细节或者模板的时候，Claude自己决定去references或者assets翻。按需取用，绝不提前堆满桌子。

这套设计妙就妙在“够用就行”。我以前写提示词，总担心信息不够，拼命塞，结果上下文爆炸，Claude反而抓不住重点。用了三层披露后，token消耗直接腰斩，效果还更稳。

还有两条原则同样重要：可组合性和可移植性。多个技能能同时加载，互不冲突，像厨房里几个厨师各司其职。一次写好，在Claude.ai、Claude Code、API上跑起来一模一样。只要环境支持依赖就行。

对已经搭好MCP服务器的朋友，指南专门留了章节。MCP负责“连得上”，技能负责“怎么用得好”。没有技能，用户连上MCP后往往不知道下一步干啥，工单里全是“这个整合怎么用”的问题。有了技能，预设流程自动触发，结果一致，学习曲线也平缓多了。

下面这张表把两者的分工说得清清楚楚：

没了技能，用户每次都得从零提示，失败率高，还容易怪罪连接器；有了技能，流程自动跑，嵌入领域经验，效果立竿见影。

🗺️ 谋篇布局：先把用例拎清楚

动笔前，指南反复强调一件事：先找2-3个具体用例。别泛泛说“帮我管理项目”，要像下面这样写清楚：

用例：项目Sprint规划
触发：用户说“帮我规划这个Sprint”或者“创建Sprint任务”
步骤：

1. 通过MCP从Linear拉取当前项目状态
2. 分析团队速度和容量
3. 建议任务优先级
4. 在Linear里创建带标签和估算的任务
   结果：Sprint完整规划好，任务已建

问自己四个问题：用户到底想完成什么？需要哪些多步流程？要用内置工具还是MCP？应该嵌入哪些领域知识或最佳实践？

Anthropic把常见用例分成三类，每类都有真实案例。

第一类是文档与资产创建。典型是frontend-design技能：
“创建有特色、生产级的前端界面，设计质量高。用于构建网页组件、页面、人工制品、海报或应用。”

关键技巧：嵌入风格指南和品牌标准、模板结构保证一致输出、最终输出前走质量检查清单。不需要外部工具，全靠Claude内置能力。

第二类是工作流自动化。skill-creator技能就是例子：
“交互式创建新技能指南。带用户走完用例定义、前言生成、指令编写和验证。”

技巧：带验证闸门的步步流程、常见结构模板、内置审查与改进建议、迭代优化循环。

第三类是MCP增强。Sentry的sentry-code-review技能：
“自动分析并修复GitHub Pull Request里检测到的bug，使用Sentry错误监控数据，通过他们的MCP服务器。”

技巧：按顺序协调多个MCP调用、嵌入领域专长、提供用户本来要自己指定的上下文、处理常见MCP问题。

🧪 定义成功：怎么知道技能在好好干活

指南给了一套 aspirational 指标，不是死板KPI，而是帮你判断方向。

定量方面：

• 相关查询里90%能自动触发。测法：跑10-20个该触发的测试句，数自动加载 vs 手动调用的次数。
• 完成流程只用X个工具调用。测法：同一任务，对比开技能前后的调用数和token消耗。
• 每个流程0次失败API调用。测法：看MCP服务器日志里的重试率和错误码。

定性方面：

• 用户不用再追问“下一步呢”。
• 流程跑完不用用户纠正。
• 不同会话结果一致，新用户第一次用也能上手。

这些指标听起来有点“ vibes-based”，但确实管用。我自己建技能时，先拿一个 hardest task 反复迭代，直到Claude一次过，再把经验抽成技能，速度比大范围测试快多了。

🛠️ 工匠手册：文件结构与前言魔法

技能文件夹长这样：

your-skill-name/
├── SKILL.md
├── scripts/
│   ├── process_data.py
│   └── validate.sh
├── references/
│   ├── api-guide.md
│   └── examples/
└── assets/
    └── report-template.md

规矩死板却重要：SKILL.md必须叫这个名字，大小写敏感。文件夹用kebab-case，不能空格、不能下划线、不能大写。文件夹里别放README.md，文档全塞SKILL.md或references里（GitHub仓库层面可以有README给人类看）。

最关键的是YAML前言。它决定Claude会不会加载这个技能。最小格式就两行：

---
name: your-skill-name
description: 它做什么。用户说[具体短语]时用。
---

name必须kebab-case，跟文件夹一致。description必须同时写清楚“做什么”和“什么时候用”（触发条件），1024字符以内，不能有尖括号< >，要包含用户可能说的具体任务和文件类型。

可选字段有license（MIT、Apache-2.0）、compatibility（环境要求）、metadata（author、version、mcp-server等）。

安全红线：前言里禁尖括号，名字里不能出现claude或anthropic（保留字）。因为前言会进系统提示，恶意内容容易注入。

写description的结构是：【做什么】+【什么时候用】+【核心能力】。好的例子具体、可行动、带触发短语：

“分析Figma设计文件并生成开发者交接文档。用户上传.fig文件、问‘设计规格’‘组件文档’或‘设计转代码交接’时用。”

坏的例子要么太模糊（“帮我做项目”），要么缺触发（“创建复杂多页文档系统”），要么只说技术不提用户怎么说。

正文部分推荐结构：先Instructions大段，拆成Step 1、Step 2，配代码示例和预期输出；再Examples小节，写常见场景的用户话术和动作；最后Troubleshooting，列常见错误、原因、解法。

最佳实践三条：指令要具体可执行，别光说“验证数据”；一定要写错误处理；需要查资料时明确指向references里的文件；保持SKILL.md聚焦核心，细节放references走渐进披露。

🧬 淬炼成金：测试、迭代与真实打磨

技能测试分三种 rigor 级别：Claude.ai里手动跑（最快）、Claude Code里脚本化测试、通过skills API做系统化评估。选哪种看你的质量要求和使用范围。

推荐做法是先盯住一个 hardest task 死磕，直到Claude稳定成功，再把经验固化成技能。之后再扩展覆盖面。

测试通常覆盖三块：

1. 触发测试：确保该触发时触发，不该触发时不触发。
   该触发：“帮我新建ProjectHub工作区”“我要在ProjectHub建项目”
   不该触发：“旧金山天气怎么样”“帮我写Python代码”

2. 功能测试：输出正确、API调用成功、错误处理管用、边缘情况覆盖。
   举例：给定项目名“Q4规划”和5个任务描述，跑完后ProjectHub里项目建好、5个任务属性正确、全都关联到项目、无API错误。

3. 性能对比：证明比基线强。
   没技能时：用户每次都要详细指令、来回15条消息、3次失败重试、消耗12000 token。
   有技能时：自动执行流程、只问2个澄清问题、0失败、6000 token。

指南还贴心推荐了skill-creator技能。它就在Claude.ai插件目录，或者能下载到Claude Code。用它描述自然语言需求，就能生成带正确前言的SKILL.md，还会建议触发短语和结构。审技能时它能指出描述模糊、触发缺失、结构问题，帮你预判过触发或欠触发风险。迭代时，把遇到的边缘case和失败例子扔回去，让它帮你改进特定处理逻辑。15-30分钟就能搭出一个能跑的技能。

其实我自己第一次用skill-creator时，还特意试了带MCP的复杂工作流。结果它不仅生成了前言，还提醒我加了错误处理分支。后来真跑起来，MCP连接偶尔抖动，技能里的重试逻辑直接救场。没它的话，我估计得来回改五六版。

写完这篇，我忽然明白指南最打动我的地方：它把“让AI稳定做事”这件事，拆成了可操作、可复制的厨房手艺。不是玄学，不是堆提示词，而是像老工匠传授秘方——先搭骨架、再填细节、最后反复淬炼。一次写好，团队里每个人、每次对话都能受益。

你现在就可以试试：挑一个最烦的重复流程，打开skill-creator，照着指南走一遍。说不定下次再跟Claude聊天，它已经先你一步把活儿干完了。

参考文献

1. Anthropic. The Complete Guide to Building Skills for Claude. 官方技能构建手册，详述渐进披露、YAML前言与三类用例实践。

2. Anthropic Engineering Blog. 关于技能元数据如何实现“恰到好处的信息披露”与token效率的论述。

3. skill-creator 技能官方描述。交互式技能创建流程，包含用例定义、前言生成与验证闸门设计。

4. Sentry. sentry-code-review 技能案例。通过MCP协调错误监控数据，实现PR自动分析与修复的端到端工作流。

5. Linear 项目管理集成示例。Sprint规划多步流程，展示MCP数据拉取与任务创建的技能封装模式。