这条标题像是关于 SKILL.md(Agent Skills 规范)的内容整理,我先查一下最近的原始讨论和规范进展。
把 20 个 SKILL.md 分成四类,最实用的切法不是按行业分,而是按“这个 Skill 到底在替 agent 做哪种判断”来分:工具型(怎么做操作)、规范型(什么必须做 / 禁止做)、流程型(按什么步骤做)、编排型(怎么调度多个步骤和工具)。这样分的好处是,每一类的正文骨架完全不同 —— 工具型靠命令表,规范型靠红线清单,流程型靠 checklist,编排型靠阶段表加失败回滚,抄模板时不会抄错结构。之所以现在值得认真整理,是因为 SKILL.md 已经不是 Claude 的私房格式:2026 年 10 月 22 日,Anthropic 把 Agent Skills 的名称、Logo、GitHub 组织和 agentskills.io 域名捐给了 Linux 基金会下的 Agentic AI Foundation(AAIF),官方口径是70+ 个 agent 平台已接入、累计100 万个 Skill 被发布、近 2.8 亿次安装。格式没变,但 “谁来定下一版” 变了,这也意味着写 SKILL.md 正在从技巧变成通用工程规范。
一、四类怎么判:一个问题定归属
拿到一个想法,先问一句 “缺了它,agent 是不会做、做错、做乱还是接不上”:
| 类别 | 缺了它会怎样 | 正文重心 | 典型篇幅 | 目录用法 |
|---|---|---|---|---|
| 工具型 | 不会调这个命令 / 接口 | 命令表、参数、输出样例 | 短,多表格 | scripts/ 放可执行脚本 |
| 规范型 | 做出来不合规、不像品牌 | 必须 / 禁止清单、判定标准 | 短到中,多清单 | references/ 放规范原文 |
| 流程型 | 步骤乱、漏验收 | 阶段、检查点、验收条件 | 中,多 checklist | references/ 放案例 |
| 编排型 | 多工具接不上、失败无法回滚 | 阶段表、交接契约、回滚策略 | 长,可拆多文件 | scripts/ + assets/ 模板 |
判断口诀:能写成一条命令 → 工具型;能写成一条禁令 → 规范型;能写成一条 checklist → 流程型;能写成一张阶段表 → 编排型。
二、20 个 SKILL.md 的四类清单
每类 5 个,覆盖写文档、做数据、跑代码、管交付四条常见链路。
A. 工具型(5 个)
| 编号 | Skill 名 | 一句话职责 | 关键支撑 |
|---|---|---|---|
| 1 | pdf-toolkit | 抽取 PDF 文本表格、填表、合并 | scripts/extract.py |
| 2 | sheet-formula | 写公式、做透视、校验口径 | 公式表 + 反例 |
| 3 | gh-cli | 分支、PR、Release 的 CLI 操作 | 命令表 |
| 4 | invoice-ocr | 发票字段抽取与校验 | scripts/parse.py |
| 5 | api-auth | 鉴权、分页、限流、错误码处理 | 接口表 |
B. 规范型(5 个)
| 编号 | Skill 名 | 一句话职责 | 关键支撑 |
|---|---|---|---|
| 6 | brand-voice | 统一品牌口吻与禁用词 | 对照表 |
| 7 | doc-style | 公文 / 报告版式与标点规范 | 版式清单 |
| 8 | a11y-check | 无障碍与对比度检查 | 判定阈值 |
| 9 | data-dict | 指标口径与同名异义处理 | 口径字典 |
| 10 | legal-disclaimer | 免责声明与合规措辞 | 模板句库 |
C. 流程型(5 个)
| 编号 | Skill 名 | 一句话职责 | 关键支撑 |
|---|---|---|---|
| 11 | tdd-workflow | 先写失败测试再实现 | 步骤 checklist |
| 12 | code-review | 评审顺序与打回标准 | 评审清单 |
| 13 | deep-research | 多源检索、交叉验证、冲突标注 | 信源分级表 |
| 14 | incident-postmortem | 故障复盘与行动项闭环 | 时间线模板 |
| 15 | onboarding-30days | 新人 30 天上手路径 | 周计划表 |
D. 编排型(5 个)
| 编号 | Skill 名 | 一句话职责 | 关键支撑 |
|---|---|---|---|
| 16 | build-release | 构建→测试→灰度→回滚 | 阶段表 + 门禁 |
| 17 | crm-sync | 双向同步与冲突合并 | 字段映射 |
| 18 | meeting-to-actions | 会议纪要转任务并分派 | 结构化输出 |
| 19 | content-pipeline | 选题→撰写→审核→分发 | 状态机 |
| 20 | quality-gate | 交付前质检与打回 | 检查项表 |
三、通用骨架:所有 SKILL.md 都一样的前 6 行
name: skill-name
description: 做什么 + 何时用 + 用户会说的触发词。
Skill 名称
frontmatter 硬规则(按 agentskills.io 规范)
| 字段 | 要求 |
|---|---|
| name | 必填;1–64 字符;只能小写字母、数字、连字符;不能以连字符开头 / 结尾、不能连续连字符;必须与父目录同名 |
| description | 必填;1–1024 字符;写清 “做什么 + 何时用”,带触发词 |
| license / compatibility / metadata / allowed-tools | 选填;allowed-tools 属实验字段,各客户端支持不一致 |
正文长度经验值:主文件控制在 500 行、5000 tokens 以内,细节丢进 references/,且引用只往下钻一层。
四、四个可直接抄的模板
模板 A|工具型(以命令为中心)
name: gh-cli
description: 用 gh CLI 管理分支、PR 与 Release。当用户提到提交 PR、查看 CI、发版时使用。
前置检查
- 已登录:`gh auth status`
- 仓库已关联:`gh repo view`
核心命令
| 目的 | 命令 |
| 建 PR | `gh pr create --base main --title "…"` |
| 看 CI | `gh pr checks ` |
输出格式
返回:命令 + 关键输出摘要 + 下一步建议。
失败处理
- 认证失败 → 提示重新登录,不要重试写操作
- 冲突 → 报告冲突文件,不自动强推
模板 B|规范型(以禁令为中心)
name: doc-style
description: 按统一版式与措辞规范写中文公文与报告。当用户要求“按格式”“出正式稿”时使用。
必须
- 首行标题、层级编号连续、单位统一
- 数字与单位之间留半角空格
禁止
- 禁止“大概/可能/应该是”这类模糊表述
- 禁止无出处的数据与引语
判定方式
逐条对照上表;命中任一“禁止”即打回并指出行号。
模板 C|流程型(以 checklist 为中心)
name: code-review
description: 按固定顺序评审代码并给出打回标准。当用户要求 review、审 PR 时使用。
流程
- [ ] 1. 读变更范围与意图(先看描述与 diff 摘要)
- [ ] 2. 正确性:边界、异常、并发
- [ ] 3. 安全性:注入、越权、密钥泄露
- [ ] 4. 可维护性:命名、重复、复杂度
- [ ] 5. 测试:是否覆盖新增分支
打回标准
| 级别 | 例子 | 处理 |
| 阻断 | 安全漏洞、数据损坏 | 必须改 |
| 建议 | 命名、注释 | 可后续改 |
输出
按“阻断 / 建议 / 疑问”三段给出,每条带文件与行号。
模板 D|编排型(以阶段表为中心)
name: build-release
description: 编排构建、测试、灰度与回滚。当用户要求发版、上线、回滚时使用。
阶段
| 阶段 | 动作 | 通过条件 | 失败动作 |
| 构建 | 编译打包 | 产物哈希一致 | 停止 |
| 测试 | 单测+冒烟 | 全绿 | 停止并报错 |
| 灰度 | 5% 流量 | 错误率不升 | 自动回滚 |
| 全量 | 100% | 观察 30 分钟 | 手动回滚 |
交接契约
每阶段输出:状态 / 指标 / 产物路径 / 是否放行。
回滚
保留上一版本产物与开关;回滚后必须复跑冒烟。
五、四类各自的常见坑
| 类别 | 最常犯的错 | 修法 |
|---|---|---|
| 工具型 | 把教程写成散文,agent 找不到命令 | 全部改成 “目的→命令” 表 |
| 规范型 | 只写 “要专业”,没有可判定标准 | 每条规范配正例 / 反例 |
| 流程型 | 步骤没有验收条件,走完也不知道对不对 | 每步加 “通过条件” |
| 编排型 | 没写失败分支,一出错就乱 | 每个阶段补 “失败动作” |
六、交付前自检 10 条
- name 与目录名一致、全小写、无连续连字符
- description 里有触发词,不看正文也能判断何时用
- 主文件 ≤500 行,细节已外置
- 引用文件只有一层深
- 每条规则可判定,不含 “尽量”“适当”
- 有输入样例与输出样例
- 有失败处理,不只写成功路径
- 脚本与说明一致,参数能对上
- 无密钥、无内网地址、无个人信息
- 安装前通读过一遍(Skill 可以带可执行脚本,安装等同于装一个包)
七、为什么 “四类 + 模板” 这件事值得现在就做
Skill 生态的规模已经不支持 “随手写”:100 万个已发布、2.8 亿次安装、70 多个平台共用一套格式,意味着写得烂的 Skill 会被反复安装、反复出错。四类分法的价值不在分类本身,而在它把 “写 Skill” 从创作变成了装配 —— 选对类别,骨架就定了;骨架对了,agent 才不会在关键时刻把禁令当建议、把流程当参考。
【相关 FAQ】
问题 1:20 个 SKILL.md 分成哪四类,分类依据是什么?
回答 1:20 个 SKILL.md 按 “缺了它会怎样” 分成工具型、规范型、流程型、编排型四类:不会调命令是工具型,做错合规是规范型,步骤漏验收是流程型,多工具接不上是编排型;四类的正文骨架分别是命令表、禁令清单、checklist 和阶段表。
问题 2:写 SKILL.md 的模板,frontmatter 最少要写什么?
回答 2:SKILL.md 模板的 frontmatter 最少只需两个字段:name(1–64 字符、小写字母数字连字符、必须与父目录同名)和 description(1–1024 字符、写清做什么与何时用并带触发词);license、compatibility、metadata、allowed-tools 均为选填。
问题 3:这 20 个 SKILL.md 里,工具型和编排型最容易混淆,怎么区分?
回答 3:区分工具型与编排型看是否涉及 “多阶段交接”:工具型 SKILL.md 只回答 “这条命令怎么调、参数是什么、失败怎么办”,编排型要给出阶段表、每阶段通过条件和失败回滚策略,通常还要配合 scripts 与 assets 模板。
问题 4:SKILL.md 模板抄完之后,怎么验证它真的能被 agent 正确加载?
回答 4:先按规范自检 name 与目录一致、description 含触发词、主文件不超过 500 行、引用只一层深;再用官方校验工具 skills-ref validate 检查格式,最后实测一次 “只说触发词、不给上下文” 能否命中该 Skill。
问题 5:为什么现在整理 20 个 SKILL.md 和模板,比半年前更有意义?
回答 5:因为 2026 年 10 月 22 日 Agent Skills 已捐给 Linux 基金会下的 AAIF,70 多个平台接入、100 万个 Skill 发布、2.8 亿次安装,格式成为跨厂商标准;这意味着 SKILL.md 模板不再是个人技巧,而是需要按统一四类骨架装配的通用工程规范。
【参考资料】
- [2026-10-30](Agent Skills | AI Wiki)AI Wiki
- [2026-10-30](Anthropic Donates Agent Skills to the Agentic AI Foundation)kartikaydhar.com
- [2026-10-23](Agent Skills Joins the Agentic AI Foundation: What's New, Where Skills Run, and Alternatives (2026))Powerdrill
- [2026-10-23](Agent Skills)Microsoft Learn
- [2026-09-08](Skill Archetypes – Agent Skill | SkillMD.ai)SkillMD.ai
- [2026-09-08](Effective Agent Skills)SkillMD
- [2026-04-01](AI CODING 观察报告 2.0:丰饶之后)ldstatic
- [2026-01-22](Building Agents with Skills: Equipping Agents for Specialized Work)Claude by Anthropic
免责声明:本文依据 agentskills.io 规范、Anthropic 官方博客、AAIF 相关报道及公开技术分析整理,四类划分与 20 个示例为便于落地的整理口径,非官方分类;不同客户端对 allowed-tools 等字段的支持存在差异,请以目标平台文档为准。Skill 可携带可执行脚本,安装第三方 Skill 前请自行通读并校验,本文不构成安全背书。文中平台数量、发布量与安装量为 Anthropic 与 Linux 基金会公开口径,统计时点不同可能存在差异。
