SKILL.md:跨工具事实标准(Anthropic Agent Skills)

影响力:2026-03 已被 32+ 主流 agent 工具读同一份 SKILL.md —— Claude Code / Cursor / OpenAI Codex / Gemini CLI / JetBrains Junie / AWS Kiro / Block Goose 全部支持。 干活密度:🔵 协议级 + 🟡 方法论级 官方规范:agentskills.io/specification(Anthropic 2025-12-18 发布)

🔥 影响力卡片

• 仓库:https://github.com/anthropics/skills(~128k stars)
• 官方 frontend-design skill:277,000+ installs(2026-03)
• 社区版 obra/superpowers:~177k stars(2026-05 实测,40.9k 已严重过时)
• 校验工具:skills-ref validate(https://github.com/agentskills/agentskills/tree/main/skills-ref)

🎯 为什么必读

如果你有任何 prompt 工程经验,你就知道 prompt 没法跨工具复用:Cursor 写的 system prompt 不能直接用在 Claude Code,Codex 的 instruction 不能搬到 Gemini CLI。SKILL.md 就是解决这个问题的协议 —— 一次写,32+ agent 工具读同一份。

不是某个公司的产品,是事实标准。这一篇能让你把团队所有 agent 配置做成可移植资产。

一句话总结

SKILL.md = AI agent 时代的 README.md;Progressive Disclosure 让大量 skill 共存而不爆炸 token。

💎 金句墙

★ “Skills are how we package agent capability. They’re the new README.md.” “Skill 是我们打包 agent 能力的方式,是新的 README.md。” —— 译者点评:这个类比精确。README.md 让人类理解 repo;SKILL.md 让 agent 理解 repo + 任务规范 + 调用约定

★ “Progressive disclosure: metadata loads at startup, body loads on trigger.” “渐进披露:metadata 启动时加载,正文按触发加载。” —— 译者点评:这是 SKILL.md 设计最聪明的一点。让你拥有 100 个 skill 不会让 token 爆炸,因为只有触发时才加载完整正文

📋 核心精读

1. 目录布局

skill-name/
├── SKILL.md        # 必需:frontmatter + 指令(< 500 行)
├── scripts/        # 可选:可执行代码(Python / shell)
├── references/     # 可选:按需载入的参考 md
└── assets/         # 可选:模板 / 图 / 数据

🟢 译者点评:scripts/ 是 skill 的最大杀器。不只是 prompt,可以挂可执行代码。Anthropic 官方 pdf skill 用 Python 处理 PDF,xlsx skill 用 openpyxl 操作 Excel —— agent 调用时直接 spawn 进程,不靠 LLM 模拟。

2. SKILL.md frontmatter 完整

---
name: pdf-processing                              # 必需,小写+连字符,匹配父目录名
description: |                                    # 必需,≤1024 字符,要写"何时用"
  Extract PDF text, fill PDF forms, merge PDFs.
  Use when user asks to read or modify PDFs.
license: Apache-2.0                               # 可选
compatibility: Requires Python 3.14+ and uv       # 可选
metadata:                                         # 可选 KV
  author: example-org
  version: "1.0"
allowed-tools: Bash(git:*) Bash(jq:*) Read        # 可选(实验)
---

# PDF Processing

When the user asks about PDFs:
1. First check if `pdftotext` is available
2. ...

## Examples

...

## See also
- references/pdf-internals.md

🟢 译者点评:description 写”何时用”是关键。agent 启动时只读 frontmatter(~100 tokens),靠 description 决定”这个 skill 适合当前 user prompt 吗”。写得越精确,agent 命中率越高,token 用得越少。

3. Progressive Disclosure 三层

启动时 loaded(~100 tokens × N skills):
  └─ 仅 frontmatter(name + description + metadata)

触发时 loaded(~5000 tokens / < 500 行):
  └─ SKILL.md body

按需 loaded(变长):
  └─ scripts/ + references/ + assets/(只有正文里 @ 引用时才读)

🟢 译者点评:这个机制让”100 个 skill 共存”成为可能。Anthropic 官方 skills 仓 17 个 + obra/superpowers 几十个 + 自定义,全部装进 ~/.claude/skills/,启动开销 ~3000 tokens 而不是 5MB。

4. 跨工具读同一份(2026-03 矩阵)

🟢 译者点评:这是 2026 年最隐蔽但影响最大的协议化进展之一。比 MCP 知名度低,但渗透率更高 —— 你写一个 skill,32+ 工具能读。

5. 校验工具

npm install -g @agentskills/skills-ref
skills-ref validate ./my-skill

会检查:

• frontmatter 必填字段
• description ≤ 1024 字符
• name 匹配父目录
• body < 500 行
• references/ 引用是否存在

🟢 译者点评:CI 必装。skill 写得再多,没校验等于没写 —— frontmatter 错一个字符 agent 就不读了。

6. 官方 17 类 skill 清单

7. 配套:AGENTS.md(项目级)

your-project/
├── AGENTS.md           # 项目级指令(LF AAIF 治理)
├── .claude/
│   ├── agents/         # Claude Code subagents
│   ├── skills/         # 项目级 skills
│   └── settings.json   # hooks
└── .cursor/
    ├── rules/*.mdc     # Cursor Rules
    └── skills/         # Cursor 同源 skills

🟢 译者点评:AGENTS.md 是”项目级 README for agents”,SKILL.md 是”能力包”。两者互补:AGENTS.md 说”这个项目什么样”,SKILL.md 说”agent 怎么干某类活”。⚠️ Claude Code 截至 2026-03 仍未原生 auto-load AGENTS.md(其他 agent 都加载了)。

🟢 译者总评

1. 现在就做:在你的 dotfiles repo 加 ~/.claude/skills/<your-skill>/SKILL.md,跑 skills-ref validate
2. 团队级:把团队的代码规范 / commit message 规范 / PR review checklist 全部写成 skills,放仓库 .claude/skills/(同时被 Cursor 等工具读)
3. 不要乱起 description:这是 agent 命中率的关键。写”何时用”,不要写”是什么”
4. frontend-design skill 是宝藏:277k+ installs 不是白拿的,默认禁用 Inter/Roboto + 强制 a11y + 强对比度,你的 AI 生成 UI 立刻有辨识度
5. 配套读:Addy Osmani 三连 的 Harness Engineering;MCP 协议
6. 关键 caveat:body 别超 500 行;否则 agent 触发时 token 开销大,得不偿失。长内容拆 references/

🔗 调研来源

• Anthropic Skills GitHub
• Agent Skills specification
• skills-ref validate
• frontend-design SKILL.md
• obra/superpowers
• Anthropic Official Skills Guide
• AGENTS.md standard
• Anthropic Skills update — Medium