好技能是只做一类事的文件夹，价值在真实踩坑的 Gotchas 与现成脚本
技能本质上是一个文件夹，整个文件系统都可以当作上下文工程和渐进披露的工具。
SKILL.md 当枢纽，只告诉 Claude 有哪些文件、什么症状读哪个文件。详细的 API 签名放 references/，输出模板放 assets/，可执行逻辑放脚本。这样常驻上下文只有一张路由表，细节等需要时才读进来，避免一上来就把所有知识塞进窗口。
“think of the entire file system as a form of context engineering” ¶64
上下文成本只用一句「增加一点」带过，没有量化清单的 token 占用，也没说技能数量的上限、description 会不会被截断。另外，技能依赖靠按名引用，被依赖的技能没装时会怎样失败，文章也没写。
好技能只做一类事。横跨多类的技能会让 agent 困惑。
作者把内部技能编目后归为九类：库/API 参考、产品验证、数据获取与分析、业务流程自动化、脚手架、代码质量、CI/CD、Runbook、基础设施运维。推断：技能是凭 description 被选中的，一个技能职责混杂，触发边界就模糊，模型很难判断该不该调用它，也很难判断调用后该走哪条分支。作者自己说这个分类不是定论，只是帮你找技能库缺口的框架。
“The best skills fit cleanly into one” ¶8
九类分类来自 Anthropic 内部编目，编目方法、样本量和归类标准都没有说明。「横跨多类的技能会让 agent 困惑」是定性观察，没有给证据。
验证类技能对输出质量的影响最可测，值得专门投入一名工程师花一周打磨。
验证技能通常配合 playwright、tmux 这类外部工具驱动真实界面或 TTY。它在每一步对状态做程序化断言，或者录下视频让人看到 Claude 到底测了什么。这样 Claude「自称完成」就变成了可以检查的证据，靠的是技能里附带的脚本，不是靠文字指令。
“Verification skills have had the most measurable impact on Claude’s output quality internally.” ¶15
「验证技能对质量的影响最可测」既没有给指标定义，也没有基线和提升幅度，没法判断「最」是相对什么说的。
技能里信号最高的部分是 Gotchas 段。它应该从 Claude 实际踩过的坑里一条条长出来，不写 Claude 本来就知道的东西。
Claude 已经会写代码、能读代码库，重复它的默认行为只会占上下文、不增加价值。真正把它推离默认路径的，是组织特有的反直觉事实：只追加不更新的表要按 version 取最新行；同一个值在两个系统里叫不同字段名；staging 环境返回 200 但 webhook 实际没处理。作者说最好的技能大多是从几行字加一条 gotcha 起步，后来不断补充才变好的。
“The highest-signal content in any skill is the Gotchas section.” ¶59
这一点暂无对应的审视。
description 是写给模型看的触发条件，不是写给人看的功能摘要。
会话一启动，Claude Code 就把所有可用技能连同 description 列成一张清单，模型扫这张清单来判断「有没有技能适合这个请求」。所以 description 应该写触发场景和用户的原话，比如「babysit」「watch CI」，而不是「一个全面的 PR 监控工具」这种泛泛的概括。
“it's a description of when to trigger this skill” ¶73
「description 写成触发条件更好」可以低成本自己复现。
把代码和函数库交给 Claude，让它把轮次花在决定下一步做什么上，而不是重写样板代码。
技能里预置一些带 docstring 的辅助函数，docstring 里顺带写明数据坑（例如注册前 user_id 为空）。遇到开放式问题时，Claude 现场生成脚本，import 这些函数组合出分析。确定性的部分由代码保证，判断和编排留给模型。
“lets Claude spend its turns on composition” ¶77
全文没有讲安全。技能可以带可执行脚本和 hooks，从 marketplace 安装等于引入别人写的代码，但文章没有提签名、审核、权限边界和供应链风险。
作者没有直接谈到这一点。
作者是 Claude Code 团队成员。「最常用的扩展点之一」「内部有几百个在用」都是自述，没有给数据。文章还顺带推广了插件 marketplace 和 Skilljar 课程，整体立场是推广 skills 生态。
技能按层展开，Claude 只在需要时往下读，整个文件系统本身就是上下文工程。
技能本质上是一个文件夹，整个文件系统都可以当作上下文工程和渐进披露的工具。
SKILL.md 当枢纽，只告诉 Claude 有哪些文件、什么症状读哪个文件。详细的 API 签名放 references/，输出模板放 assets/，可执行逻辑放脚本。这样常驻上下文只有一张路由表，细节等需要时才读进来，避免一上来就把所有知识塞进窗口。
think of the entire file system as a form of context engineering
¶64 ↗
好技能只做一类事。横跨多类的技能会让 agent 困惑。
作者把内部技能编目后归为九类：库/API 参考、产品验证、数据获取与分析、业务流程自动化、脚手架、代码质量、CI/CD、Runbook、基础设施运维。推断：技能是凭 description 被选中的，一个技能职责混杂，触发边界就模糊，模型很难判断该不该调用它，也很难判断调用后该走哪条分支。作者自己说这个分类不是定论，只是帮你找技能库缺口的框架。
The best skills fit cleanly into one
¶8 ↗
验证类技能对输出质量的影响最可测，值得专门投入一名工程师花一周打磨。
验证技能通常配合 playwright、tmux 这类外部工具驱动真实界面或 TTY。它在每一步对状态做程序化断言，或者录下视频让人看到 Claude 到底测了什么。这样 Claude「自称完成」就变成了可以检查的证据，靠的是技能里附带的脚本，不是靠文字指令。
Verification skills have had the most measurable impact on Claude’s output quality internally.
¶15 ↗
技能里信号最高的部分是 Gotchas 段。它应该从 Claude 实际踩过的坑里一条条长出来，不写 Claude 本来就知道的东西。
Claude 已经会写代码、能读代码库，重复它的默认行为只会占上下文、不增加价值。真正把它推离默认路径的，是组织特有的反直觉事实：只追加不更新的表要按 version 取最新行；同一个值在两个系统里叫不同字段名；staging 环境返回 200 但 webhook 实际没处理。作者说最好的技能大多是从几行字加一条 gotcha 起步，后来不断补充才变好的。
The highest-signal content in any skill is the Gotchas section.
¶59 ↗
description 是写给模型看的触发条件，不是写给人看的功能摘要。
会话一启动，Claude Code 就把所有可用技能连同 description 列成一张清单，模型扫这张清单来判断「有没有技能适合这个请求」。所以 description 应该写触发场景和用户的原话，比如「babysit」「watch CI」，而不是「一个全面的 PR 监控工具」这种泛泛的概括。
it's a description of when to trigger this skill
¶73 ↗
把代码和函数库交给 Claude，让它把轮次花在决定下一步做什么上，而不是重写样板代码。
技能里预置一些带 docstring 的辅助函数，docstring 里顺带写明数据坑（例如注册前 user_id 为空）。遇到开放式问题时，Claude 现场生成脚本，import 这些函数组合出分析。确定性的部分由代码保证，判断和编排留给模型。
lets Claude spend its turns on composition
¶77 ↗
作者是 Claude Code 团队成员。「最常用的扩展点之一」「内部有几百个在用」都是自述，没有给数据。文章还顺带推广了插件 marketplace 和 Skilljar 课程，整体立场是推广 skills 生态。
「验证技能对质量的影响最可测」既没有给指标定义，也没有基线和提升幅度，没法判断「最」是相对什么说的。
九类分类来自 Anthropic 内部编目，编目方法、样本量和归类标准都没有说明。「横跨多类的技能会让 agent 困惑」是定性观察，没有给证据。
「description 写成触发条件更好」可以低成本自己复现。
全文没有讲安全。技能可以带可执行脚本和 hooks，从 marketplace 安装等于引入别人写的代码，但文章没有提签名、审核、权限边界和供应链风险。
上下文成本只用一句「增加一点」带过，没有量化清单的 token 占用，也没说技能数量的上限、description 会不会被截断。另外，技能依赖靠按名引用，被依赖的技能没装时会怎样失败，文章也没写。