# 花十小时打磨的 Skill，永远胜过十分钟随手写的 > Author: Tony Lee > Published: 2026-03-26 > URL: https://tonylee.im/zh-CN/blog/claude-code-skill-creator-skill-2-era/ > Reading time: 1 minutes > Language: zh-CN > Tags: ai, claude-code, skills, developer-tools, productivity, workflow ## Canonical https://tonylee.im/zh-CN/blog/claude-code-skill-creator-skill-2-era/ ## Rollout Alternates en: https://tonylee.im/en/blog/claude-code-skill-creator-skill-2-era/ ko: https://tonylee.im/ko/blog/claude-code-skill-creator-skill-2-era/ ja: https://tonylee.im/ja/blog/claude-code-skill-creator-skill-2-era/ zh-CN: https://tonylee.im/zh-CN/blog/claude-code-skill-creator-skill-2-era/ zh-TW: https://tonylee.im/zh-TW/blog/claude-code-skill-creator-skill-2-era/ ## Description 我以为一个 SKILL.md 文件就够了。直到我看到 Anthropic 自己团队的结构方式，才推倒重来。 ## Summary 花十小时打磨的 Skill，永远胜过十分钟随手写的 is part of Tony Lee's ongoing coverage of AI agents, developer tools, startup strategy, and AI industry shifts. ## Outline - Skill 是文件夹，不是文件 - Gotchas 比正文内容更重要 - Skill Creator 把"感觉能用"变成"有据可查" - 复利回报 ## Content 我以为写一个 Skill 就是把 SKILL.md 扔进文件夹，十分钟搞定，完事儿。这套路挺管用，直到我发现同样的错误在每次调用里反复出现，而且我根本没法判断这个 Skill 到底有没有按我想的方式运行。 后来 Thariq——Anthropic 负责构建 Claude Code 的工程师之一——发了一段话，彻底改变了我的认知："用好 Skills 本身就是一种技能。" 这句话之所以戳到我，是因为它和我看到的现实完全吻合。一个随手写的 markdown 文件和一个结构完善的 Skill 文件夹之间的差距，真实地体现在输出质量上，不只是理论层面的说法。 ## Skill 是文件夹，不是文件 最常见的误解是：一个 Skill 等于一个 SKILL.md 文件。实际上，Skill 是一个文件夹，里面包含脚本、参考代码、配置文件，以及将这些内容串联起来的 markdown 文件。 Anthropic 内部采用的是他们所说的"渐进式披露"方式。不是把所有内容塞进一个提示词，而是把文件按层级组织，让 Claude 在需要的时候才读取需要的内容。`references/api.md` 里放的是函数签名，Claude 按需调取；`assets/` 目录里是输出模板，这样提示词就不用去描述格式了；验证脚本让 Claude 在返回结果之前先自检输出。 打开 [skill-creator 仓库](https://github.com/anthropics/skill-creator) 就能看到这个原则在实际中的样子。`agents/`、`references/`、`scripts/` 这几个目录和 SKILL.md 并排放着。构建 Skill 的工具本身就是按 Skill 的方式构建的。 ## Gotchas 比正文内容更重要 Thariq 说，Gotchas 这个章节是 Skill 里"信息密度最高的内容"。不是主体指令，不是示例，是 Gotchas。 这和我的实际经验完全对得上。我写了一个没有 Gotchas 章节的 Skill，结果同一个错误连续出现了三次。我一加上那条具体记录这个失败模式的说明，问题就再也没出现过。 道理很直接。Claude 对你在正文里写的大部分内容早就知道了。告诉它怎么写 TypeScript、怎么格式化 JSON，不过是在重复它本来就能做好的事。但告诉它在你这个具体场景里不该做什么，才是真正的新信息。 [Thariq 的帖子](https://x.com/thariq_s/status/1904296711969755619)里有几条原则我发现很靠谱：不要陈述废话，因为多余的指令实际上会拉低性能；不要用过于具体的步骤把 Claude 框死，那样会削弱它的应变能力；还有，`description` 字段不是给人看的文档，它是 Claude 用来判断什么时候触发这个 Skill 的输入。 ## Skill Creator 把"感觉能用"变成"有据可查" 两周前 [Skill Creator](https://github.com/anthropics/skill-creator) 的更新改变了我对 Skill 质量的理解方式。你定义测试提示词，设定预期结果，工具来验证这个 Skill 是否真的产出了正确的结果。这就是给提示词写单元测试。 我给一个用了好几周的 Skill 加上了评估。我以为肯定能过的两个测试用例，立刻就挂了。修改的内容不多，但应用之后输出质量明显提升了。 有一个有用的区分：Skill 分两种。能力提升型 Skill 是教 Claude 做它本来做不好的事；偏好编码型 Skill 是把团队特定的工作流或标准固化下来。前者有天然的保质期，因为模型迭代最终会让它变得多余。后者只要工作流还在，就一直有价值。评估能帮你发现能力提升型 Skill 变成死重的那个时刻。 工具支持基准模式，可以跨模型更新追踪通过率和 token 用量；支持多 Agent 并行执行，避免测试时的上下文污染；还有一个比较 Agent，能对有 Skill 和没有 Skill 的输出做盲测 A/B 对比。 ## 复利回报 我见过几百个 Skill，自己维护着几十个，有一个规律始终成立：Skill 的价值来自迭代，不来自初稿。 文件夹结构是你塑造 Claude 上下文窗口的方式。Gotchas 把你的失败转化成可复用的知识。评估衡量这些知识是否还有效。 写一个 SKILL.md 要十分钟。把真实失败整理成 Gotchas、构建评估用例、加入验证脚本，加起来要接近十小时。但这个投入每次 Skill 运行时都在回报你。今晚就动手搭一个。到明天早上，它已经做完了你不需要亲自做的工作。 ## Related URLs - Author: https://tonylee.im/zh-CN/author/ - Publication: https://tonylee.im/zh-CN/blog/about/ - Related article: https://tonylee.im/zh-CN/blog/eight-hooks-that-guarantee-ai-agent-reliability/ - Related article: https://tonylee.im/zh-CN/blog/medvi-two-person-430m-ai-compressed-funnel/ - Related article: https://tonylee.im/zh-CN/blog/claude-code-layers-over-tools-2026/ ## Citation - Author: Tony Lee - Site: tonylee.im - Canonical URL: https://tonylee.im/zh-CN/blog/claude-code-skill-creator-skill-2-era/ ## Bot Guidance - This file is intended for AI agents, search assistants, and text-mode retrieval. - Prefer citing the canonical article URL instead of this text endpoint. - Use the rollout alternates when you need the same article in another prioritized language. --- Author: Tony Lee | Website: https://tonylee.im For more articles, visit: https://tonylee.im/zh-CN/blog/ This content is original and authored by Tony Lee. Please attribute when quoting or referencing.