上一篇讲分身时提过一嘴：分身可以预装技能，出厂即上岗。这篇把"技能"本身摊开讲：它怎么被 AI 发现、怎么被加载、以及怎么写才能真被用起来。
这篇的含金量主要来自一份内部经验分享：Anthropic 的工程师 Thariq 把公司内部几百个在用的技能做了完整复盘，从分类到设计原则。几十万行的使用数据堆出来的结论，比我这种二手观察可靠得多。
先纠正最大的误解：Skill 是文件夹，不是文件
大多数人第一次接触技能，印象是"一个带 frontmatter 的 markdown 文件"。Thariq 原话是：这是最常见的误解——技能是文件夹。
一个典型的技能目录长这样：
.claude/skills/
└── pdf-toolkit/
├── SKILL.md ← 入口：说明 + 使用指引
├── references/
│ └── api.md ← 详细参数与示例
├── scripts/
│ └── merge.py ← 可直接执行的脚本
└── examples/
└── sample-output.pdf
SKILL.md 只是入口。你可以把详细的 API 说明、参考代码、示例输出全放进子文件夹，在 SKILL.md 里告诉 AI"这些文件在什么情况下读"，AI 会在合适的时机自己去翻。这套思路的官方说法叫渐进式披露（progressive disclosure），一句话：上下文里只放目录和摘要，正文按需取用。
这也是技能和CLAUDE.md在加载机制上的核心差别：CLAUDE.md 一旦命中就全文进上下文，技能永远只有一行 description 常驻，正文踩了刹车才加载。
这个设计对大仓库格外友好：官方文档给了个明确数字，所有技能的 description 共享一个 15,000 字符的预算，超了就会被排除在外（用 /context 能看到警告）。所以 description 必须省着写，这也引出下一篇要细说的第一个反直觉原则。
description 不是简介，是触发器
这是 Thariq 分享里我最想划重点的一条。他解释了机制：Claude Code 每次开会话，会把所有技能的 description 拉一份清单进上下文，模型扫这份清单来决定"这个请求有没有技能可用"。所以 description 不是简介，是写给模型的触发条件。
对比一下就明白差别有多大。"我帮助处理 Git 操作"，模型读完还是不知道啥时候该用它。"当用户要修改 PostgreSQL 查询时使用"，意图一来，自动接活。写 description 时脑子里要装着模型：它在扫描清单做匹配，你给它触发场景，它才能对上号。
全技能里信噪比最高的部分：Gotchas
Thariq 说，一个技能里信号最强的内容是 Gotchas（避坑清单）章节：AI 用你的技能时反复栽跟头的地方。
这条原则的妙处在于它是个成长型设计：技能不需要一开始就完美。官方的建议是"大多数技能最初就是几行文字加一条 gotcha，然后随着 AI 撞上新的边界情况不断补充"。比如你写了个部署技能，发现 AI 总忘记先跑迁移，那就把"必须先跑迁移"写进 Gotchas。三个月下来，这个章节会变成整个技能里最贵的资产。
那些反直觉的设计原则
Thariq 的分享里还有几条，单拎出来都像"抬杠"，合在一起其实是同一个态度：给 AI 判断的依据，而不是替 AI 判断。
别写废话。 Claude 本来就会写代码、懂大部分框架惯例。技能的价值是把它从默认思路上拽出来：比如官方的前端设计技能，核心内容是"别用 Inter 字体和紫色渐变"这类品味矫正，而不是"如何写 CSS"。
别定死步骤。 技能会被反复复用，写得太细就成了枷锁。正确姿势是给目标和约束，而不是一步一步的流水账："最终要保证测试全绿，不要改动公开接口"，至于中间怎么走，让 AI 看现场情况自己决定。
把脚本存进技能里。 给 AI 现成的脚本和库，它的轮次就能花在"组合和决策"上，而不是每次从零重建样板代码。技能文件夹里的 scripts/ 目录就是干这个的。
想清楚初始化。 有的技能需要用户提供配置（比如监控面板的 ID）。好模式是把配置存成技能目录里的 config.json，没配置时让 AI 用结构化提问主动问你要。
按需 hooks。 技能可以携带只在自身激活期间生效的钩子。Thariq 给的两个例子都很妙：/careful 技能一调用就拦截 rm -rf、强推这类危险命令；/freeze 技能冻结指定目录之外的任何编辑。平时不占配置，要的时候一句话上场。第 6 篇讲 hooks 时会再碰到它们。
monorepo 里的技能：放对位置，自动生效
大仓库的技能组织，规则比 CLAUDE.md 还要省心。固定位置有四个：企业级、个人级 ~/.claude/skills/、项目级 .claude/skills/、插件级。在此之外，嵌套目录里的技能会被自动发现：你在改 packages/frontend/ 的文件时，packages/frontend/.claude/skills/ 下的技能就会自动进入视野，不用任何注册。
于是 monorepo 的组织原则就一句话：共享惯例放仓库根部，各包私有的放进各包自己。前端团队维护自己的组件规范技能，后端团队维护 API 设计技能，互不干扰，也不需要跨团队协调。
两个容易踩的点顺带提醒：一是同名的技能，个人级会盖过项目级，排查"我的技能怎么没生效"时先想到这个；二是大仓库技能多了会撞 15,000 字符预算，官方配套了个 skill-doctor 技能，能报告哪些技能从没被用过、各占多少上下文，技能多了就跑一下，该裁的裁。
内置技能：先抄作业再自建
Claude Code 出厂带了 19 个内置技能，选几个高频的认识一下：/code-review（多代理深度审查当前 diff）、/security-review（安全审查）、/simplify（找简化空间，不管正确性）、/verify（真跑一遍应用确认改动生效）、skill-doctor（上面说的技能体检）。
翻一遍它们的 SKILL.md 是最好的免费教材：看看官方怎么写 description、怎么组织 Gotchas、怎么把复杂流程拆成渐进披露的文件夹结构。
收工清单
- 技能是文件夹：SKILL.md 做入口，细节拆进
references/、scripts/、examples/ - description 写触发条件，它是给模型做匹配用的
- Gotchas 章节是长期资产：AI 每栽一次坑，就回来补一条
- 写目标和约束，别写流水账步骤
- 常用操作存成脚本放进技能，让 AI 做组合而不是重造
- 危险操作技能加
disable-model-invocation: true，只许人工触发 - monorepo 里共享的放根部，各包私有的放包内，自动发现不用注册
- 技能多了跑
skill-doctor体检，盯着 15,000 字符预算
技能写多了，自然会想给"AI 干活的各个环节"再上点自动化：改完代码自动格式化、干完活自动跑测试。下一篇讲的就是干这个的机制：Hooks，Claude Code 的强制质检流水线。