Agent Skills已经从Claude Code的专属功能变成跨Agent标准，Anthropic官方skills仓库冲到17万星。但对13.8万个公开SKILL.md的审计泼了冷水：68%缺触发词，73%达不到官方质量线。问题不在工具，在于大多数人把Skill写成了”温馨提示”。这篇文章拆5个真实封装案例，从50行的commit规范到带脚本的自动化审稿流水线，每个都能直接抄。
你的AI，每天都在重新学一遍你的规矩
同一个仓库，周一把提交信息规范讲了一遍，周三AI又写出fix bug，你再讲一遍。周五换了个会话，它忘得干干净净。
这不是模型笨，是你的知识没有落盘。规则文件（AGENTS.md/CLAUDE.md）解决”这个项目是什么”，但还有一大类知识没地方放：做某件事的固定流程。发一篇文章要走几步、审一段代码看哪几个维度、发布前跑哪些检查——这些是动作，不是事实。塞进规则文件，它们会在每一次对话里白占上下文；不存下来，你就永远在重复输入。
2025年10月Anthropic给出的答案是Agent Skills：一个文件夹加一份SKILL.md，Claude在需要时自动把全文装进上下文。一年过去，这件事的规模可以看两个数字：Anthropic官方skills仓库已有17.2万星；2026年2月26日，Anthropic和Hugging Face在同一天各自开源了官方skills目录。Skills已经从”某个工具的插件机制”变成了行业级标准——agentskills.io在推中立规范，微软在3月发布了跨Agent的Agent Skills SDK。
但繁荣的数据下面有一条裂缝。有人审计了138,000个公开SKILL.md：68%没有写触发短语，62%没有版本号，55%没有代码示例，41%连20个词都不到。按Anthropic自己的14条标准打分，73%的Skill不合格。
也就是说，绝大多数人装了Skill，却没让它真正”触发”。这篇文章要讲的，就是剩下那27%是怎么写的。
90秒理解Skill的工作原理
先讲清楚机制，后面每一条实战都建立在它上面。
一个Skill就是一个目录：
my-skill/
├── SKILL.md # 必需：元数据 + 指令正文
├── scripts/ # 可选：可执行脚本
│ └── validate.sh
├── references/ # 可选：深度参考文档
│ └── api-guide.md
└── assets/ # 可选：模板等静态资源
└── report-template.md
它高效的核心是渐进式披露（Progressive Disclosure），内容分三层加载：
| 层级 | 内容 | 何时进入上下文 | 体量建议 |
|---|---|---|---|
| 第1层 | YAML frontmatter（name + description） | 会话启动，常驻系统提示词 | 100词左右 |
| 第2层 | SKILL.md正文 | Claude判断任务匹配时才读取 | <500行 |
| 第3层 | 附加文件和脚本 | 按需读取，脚本只回传输出 | 不限 |
打个比方：第1层是名片，第2层是打开文件夹细谈，第3层是让他去资料室自己翻，翻完只跟你汇报结论。脚本尤其妙——代码本身永远不进上下文，只有运行结果进入。
这套机制有两个直接推论，后面反复用到：
- description是唯一的触发开关。 启动时模型只看得到每个Skill的name和description，写得含糊，Skill就是摆设。那份审计里68%的失败案例，都栽在这一行字上。
- 正文压得越短，触发后代价越小。 Skill Lab对官方仓库的扫描显示，连Anthropic自家的skill-creator正文都超了5000 token预算（实测约8156）——官方文档建议正文控制在500行以内，这条线人人都该守。
实战一：50行锁定团队规范（commit格式Skill）
从最小的开始。痛点：AI写的commit message永远是fix bug级别。
目录放哪？个人通用技能放~/.claude/skills/，项目专属放项目根目录的.claude/skills/（提交到Git，全组共享）。Codex、Gemini CLI等工具则认AGENTS.md体系，同一个文件两边都能兼容。
---
name: commit-format
description: 按团队规范生成commit message。当用户说"commit"、"提交"、"写提交信息"时使用。
---
生成commit message，必须遵守：
1. 主题行≤72字符，格式为`[模块名] 动词+对象`，现在时，不加句号
2. Body解释"为什么改"，不罗列"改了什么"——diff自己会说话
3. Footer标注需求单号：`Refs: PROJ-XXXX`
4. 破坏性变更必须在主题行加`!`并在Body首行写`BREAKING CHANGE:`
禁止：
- "fix bug"、"update code"、"优化了一些逻辑"这类空描述
- 一个commit混入两个不相关改动——先建议拆分
三个细节值得说：
- description里直接埋了触发词：”commit”、”提交”、”写提交信息”。模型做语义匹配时，这就是命中关键词。
- 禁止清单比要求清单值钱。 AI最常犯的错你最有体感，把它们显式写出来。
- 指令要”可执行”。 “写得专业一点”是废话，”≤72字符、现在时、加单号”是AI能逐条核对的检查项。
这个Skill总成本：常驻上下文约40 token，触发时不到500 token。比起每次会话手动贴一遍规范，这是纯赚。
实战二：踩坑知识库（内部SDK使用Skill）
Claude Code团队6月发文复盘内部Skill用法，把它们归成九类，其中”库/SDK使用说明”类最典型：教AI正确使用你们内部的库，附上参考代码片段和一页”坑列表”。
假设你们有个内部RPC框架fast-rpc，AI每次都按通用套路写，超时、重试、连接池全错：
fast-rpc/
├── SKILL.md
└── references/
└── examples/
├── basic-call.py
├── timeout-retry.py
└── streaming.py
SKILL.md正文的结构：
---
name: fast-rpc-usage
description: 使用内部RPC框架fast-rpc编写服务调用代码时使用。覆盖超时、重试、连接池配置。
---
fast-rpc不是gRPC，别按通用套路写。
核心差异（必读）：
1. 超时单位是毫秒不是秒——`timeout: 3000`是3秒，写3就成3毫秒了
2. 默认不重试。幂等接口手动开`retry_policy=RetryPolicy(idempotent=True)`
3. 连接池必须显式关闭，否则泄漏fd，压测时表现为诡异超时
示例代码见 references/examples/，按场景选：
- 普通调用 → basic-call.py
- 带重试的超时控制 → timeout-retry.py
- 流式接口 → streaming.py
这个模式的精髓在第三层：SKILL.md只放”坑列表”这种高密度信息，代码示例放references/目录，AI按需去读。如果你把三个示例全文都塞进正文，每次触发多花2000 token；拆出去，90%的调用只花300。
Claude Code团队还有一条经验值得抄进脑子里：别写显而易见的东西。Claude本来就会写代码、会读你的代码库，Skill的价值是把它推出默认思路——”超时单位是毫秒”这句话，比你写十段”如何写好Python”都有用。
实战三：把验收标准固化（验证类Skill）
同一场分享里有个结论分量很重：验证类Skill对Claude输出质量的提升，在他们内部是可测量的项里最大的。
原因不复杂：AI说”我做完了”和”真的做完了”之间，差一套你认可的验收动作。不定义，它就按自己的理解糊弄；定义了，它每次跑同一套检查。
以”改完前端必须过Playwright验证”为例：
---
name: verify-ui
description: 修改前端代码后验证UI是否正常。改完任何.tsx/.vue文件后、宣布完成前必须执行。
---
宣布任务完成前，按顺序执行：
1. pnpm typecheck && pnpm lint —— 任一失败，修复后重来
2. pnpm dev 起本地服务，等端口就绪
3. 用Playwright打开受影响页面，截图
4. 对照截图确认：无控制台报错、关键交互可点、无布局错乱
5. 全部通过才允许输出"完成"，否则继续修
禁止跳过第3步。禁止只跑typecheck就宣布完成。
配合Hooks食用更佳——PostToolUse挂钩点在AI每次改文件后自动跑格式化，AgentStop在它报告完成时强制跑验证脚本。Skill负责”教它该做什么”，Hooks负责”不做就过不去”，一软一硬。
实战四：多文件协作的Skill（以本站发布流程为例）
前三个案例都是单文件小Skill。当流程变复杂——比如一个内容团队的发布流水线——就轮到目录结构和第三层文件发挥作用了。
一个真实向的例子，发布流程Skill：
publish/
├── SKILL.md # 流程总览 + 质量门禁
├── references/
│ ├── style-guide.md # 写作风格细则
│ └── seo-checklist.md # SEO检查清单
├── scripts/
│ ├── wordcount.py # 字数与关键词密度统计
│ └── wp_publish.py # WordPress REST API发布脚本
└── assets/
└── frontmatter-template.md
SKILL.md是路由加门禁，不到100行：
---
name: publish-article
description: 发布文章到WordPress博客。当用户说"发布"、"publish"、"推到blog"时使用。
---
发布流程，顺序不可乱：
## 门禁（不通过就停，报告哪条不过）
1. 正文≥1500词 → 跑 scripts/wordcount.py
2. frontmatter完整（title/status/date）→ 对照 assets/frontmatter-template.md
3. 内链≥2条、meta description≤155字符 → 人工核对清单见 references/seo-checklist.md
## 发布
4. 读取定稿 → 跑 scripts/wp_publish.py（凭据从环境变量读，禁止硬编码）
5. 保存API响应JSON到发布记录目录
6. 输出发布结果：文章ID、链接、分类
## 失败处理
- API返回401 → 停止，提示检查WP_APP_PASSWORD，不要重试
- 分类ID不存在 → 停止并列出可用分类，不要猜
这套结构的好处：
- SKILL.md只做路由：每一步指向具体文件，正文本身很轻
- 脚本承担确定性：字数统计、API调用让Python干，AI只负责判断和编排——这就是”让AI计算，而不是让AI阅读”在Skill层的翻版
- 失败处理显式写出：401就停、不要猜分类ID，把”AI最危险的自作主张”提前堵死
实战五：给Skill做质量审计（用Skill管Skill）
Skill写得顺手就会停不下来，装到三四十个之后，新问题来了：哪些该合并？哪些description互相打架？哪些根本从没触发过？
Claude Code v2.1.128之后，/skills命令支持搜索过滤，能看装了什么；但”写得好不好”还得靠审计。社区已经有现成的做法——把一份审计清单文档直接丢给Claude，让它逐个给Skill打分。
审计维度（综合Anthropic官方文档和社区审计报告）：
| 维度 | 检查项 | 常见死法 |
|---|---|---|
| name | 小写+连字符，≤64字符，禁用claude/anthropic字样 | 命名成”helper”这类无信息量的词 |
| description | ≤1024字符，含触发词，写清使用场景 | 太短被截断，或含糊到永不匹配 |
| 正文 | <500行，高信号内容放前面 | 超长导致触发即爆炸（官方skill-creator自己都超标） |
| 引用 | 内链文件、脚本路径真实存在 | Skill Lab扫官方仓库都扫出一堆断链 |
| 触发 | 用真实任务试10次，统计命中率 | 从未触发过——装了等于没装 |
最后一行最重要。Skill不是写完就完，触发率是唯一硬指标。给你两个实操建议：
- A/B测试法：同一任务，开Skill跑一次、关Skill跑一次，对比输出差异。没差异的Skill要么删掉，要么重写description。
- 防冲突：两个Skill的description高度相似时，模型会随机命中一个。审计时把所有description拉出来对着看一遍，确保互斥。
顺带一提，${CLAUDE_EFFORT}这类变量可以在Skill里引用当前effort级别，让高投入模式跑深度检查、赶工模式快速过——审计的时候也可以顺手检查这条用了没有。
四个新手常踩的坑
坑基本都踩在同样几个地方，列出来帮你绕行：
1. description写成产品说明书。 “这是一个帮助开发者格式化代码的工具”——模型关心的是”什么时候用它”，不是”它是什么”。正确写法是场景+触发词：”当用户提交Python代码或说’格式化’时使用”。
2. 把Skill当知识库灌。 有人把整本文档拆成几十个Skill，指望AI”用到哪查哪”。但Skill是流程封装，不是检索系统——纯知识该走RAG或直接放references文件。判断标准：这个Skill描述的是一个动词（做某事），还是一个名词（某领域知识）？名词就该换方案。
3. 指令写得太”文明”。 “建议尽量考虑遵循以下规范”——模型收到的是可遵守可不遵守。Anthropic自家skill-creator的原话是让description”写得更强势一点（a little bit pushy）”，因为模型天然倾向undertrigger（触发不足）。命令式、”必须”、”禁止”，别客气。
4. 脚本路径会腐烂。 第三层文件不受上下文约束，于是大家什么都往里塞。半年后skill-creator这种头部Skill都被扫出失效资源路径，你的更别侥幸。Skill要跟着版本控制走，改了脚本顺手更新SKILL.md里的引用——把它当代码管，别当文档管。
结语
回过头看，Skills解决的还是那个老问题：怎么让AI稳定地复现你脑子里的最佳实践。
规则文件告诉它”你是谁”，MCP给它接上工具，Skills教会它”这类事该怎么做”。三者各管一层，缺哪个，哪一层就靠运气。
138,000个公开Skill的审计数据说明，大多数人还停在”装了”这一步。而从”装了”到”好用”，中间隔的无非是：一条带触发词的description、一份500行以内的高信号正文、几个真实存在的脚本文件，加上每周看一眼触发率。
工具已经全部就位，标准也已经是公开的。下一个动作在你：打开终端，把你这周重复输入超过两次的那段提示词，变成你的第一个SKILL.md。
