anthropic/skills — 架构与原理

30 秒导读: 这个仓库是 Anthropic 官方的 Agent Skills 示范集——17 个真实 skill(PDF/Word/Excel 处理、MCP 生成、品牌排版、网页测试……)外加一个能造 skill 的元 skill。一个 skill 就是一个带 SKILL.md 的文件夹:SKILL.md 顶部的 YAML description 决定 Claude 什么时候用它,正文教 Claude 怎么做,旁边的 scripts/ references/ assets/ 按需加载。核心思想只有一个词:渐进式披露(progressive disclosure)——别一次把所有知识塞进上下文,而是分三级、用到才取。

1. 这是什么(零基础也能懂)

一句话定义: Skill 是一个文件夹形态的『操作手册 + 工具箱』,Claude 在遇到对口任务时动态加载它,从而把某类专门任务(按公司品牌做 PPT、填 PDF 表单、写 MCP server……)做得又稳又像样。

解决什么问题。 大模型什么都会一点,但「会一点」和「按你们团队的固定流程稳定地做对」之间差着一截。

你不想每次都把「我们公司的品牌色是 #d97757、标题用 Poppins」重新打一遍。
你也不想把这段知识硬塞进系统提示——它只在做设计时才有用,平时白占上下文。

Skill 就是把这段「领域知识 + 固定步骤 + 现成脚本」封装成一个文件夹,平时只露出一行简介,真用到了才整份展开。

给谁用。 给在 Claude Code / Claude.ai / Claude API 上跑活的人:把一段反复出现的工作流「沉淀」下来,以后一句话就触发。

用起来什么样。 在 Claude Code 里把这个仓库当插件市场装上,然后直接用大白话叫它:

/plugin marketplace add anthropics/skills
# 装上 document-skills 后,直接说:
用 PDF skill 把 path/to/some-file.pdf 里的表单字段抽出来

你没有点名「用哪份手册」也行——只要任务对得上某个 skill 的 description,Claude 会自己决定要不要翻开它(触发机制见 §3)。来源:README.md 的 Try in Claude Code 一节。

一句话直觉/类比。 把 skill 当成贴在工位墙上的 SOP 卡片:卡片标题(description)让你一眼知道「这是干这个的」;真要照做了,才把卡片翻到背面看详细步骤(SKILL.md 正文);需要量尺子/计算器时,再去抽屉里拿工具(scripts/)。你不会把所有卡片背面都背在脑子里——用到哪张翻哪张。

本节不碰任何底层代码。记住一件事就够:skill = 文件夹;frontmatter 触发;按需加载。

2. 顶层全景(它大概怎么转)

这一节给你看「大盘」:一个 skill 从被发现到被执行,经过哪几层。

2.1 一个 skill 文件夹长什么样

skill-name/
├── SKILL.md            ← 必需。顶部 YAML(name/description)+ 正文(指令)
├── scripts/            ← 可选。确定性/重复活儿的现成脚本,可直接执行而不读进上下文
├── references/         ← 可选。按需读进上下文的细节文档(大文件带目录)
└── assets/             ← 可选。产出里要用的素材(模板、图标、字体)

来源:skills/skill-creator/SKILL.md「Anatomy of a Skill」一节(约 75-84 行)。

2.2 三级渐进式披露(整个系统的灵魂)

Skill 的加载分三级,越往下越贵、越按需:

级别	内容	何时进上下文	体量约束
L1 元数据	`name` + `description`	始终在场(出现在 Claude 的 `available_skills` 列表里)	~100 词
L2 正文	`SKILL.md` 的 markdown 主体	该 skill 被触发时	理想 <500 行
L3 捆绑资源	`scripts/ references/ assets/`	正文指示去读/去跑时	不限(脚本可直接执行,无需读入)

来源:skills/skill-creator/SKILL.md「Progressive Disclosure」(约 86-99 行)。这张表是理解整个仓库的钥匙——详见 01 章。

2.3 主线:一次 skill 调用怎么走完

下面这张图从左到右是时间顺序;关键是看「上下文里此刻装了什么」如何一级级膨胀。

用户说一句话
     │
     ▼
┌─────────────────────────────┐
│ L1 永远在场:所有 skill 的     │   Claude 读每个 description,
│ name + description 列表        │   判断「这任务该不该翻某张卡」
└─────────────────────────────┘
     │  命中某个 skill 的 description
     ▼
┌─────────────────────────────┐
│ L2 载入该 skill 的 SKILL.md    │   正文里有「需要 X 时去读 references/x.md」
│ 正文(指令 + 决策树 + 表格)    │   「重复活儿跑 scripts/y.py」之类的指针
└─────────────────────────────┘
     │  正文指示「去读/去跑」
     ▼
┌─────────────────────────────┐
│ L3 按需:读 references/ 某文件   │   只把这一次真正需要的细节
│      或 执行 scripts/ 某脚本    │   拉进上下文;脚本甚至可只跑不读
└─────────────────────────────┘
     │
     ▼
  完成任务 / 产出文件

怎么读这张图: 上下文不是一开始就塞满,而是命中才下钻。L1 便宜(永远在),所以 description 写得准不准是成败关键;L2 是「这类任务的总纲」;L3 才是又长又专的细节,用到才取。

2.4 仓库目录(部件一句话职责)

部件	干什么	在哪
17 个 skill	真实可用的能力示范	`skills/*/`
元技能 skill-creator	造 skill + 评测 skill + 优化触发	`skills/skill-creator/`
插件市场清单	把 skill 分组成可安装的插件	`.claude-plugin/marketplace.json`
spec(占位)	指向线上规范的重定向	`spec/agent-skills-spec.md`
模板	新 skill 的起点(只有 frontmatter + 一行)	`template/SKILL.md`

一个诚实提示: spec/agent-skills-spec.md 在本 commit 里只有一句重定向到 agentskills.io/specification,正文不在克隆内。所以本组文档讲到「frontmatter 契约」时,以仓库里真实执行的校验代码 skills/skill-creator/scripts/quick_validate.py 为准,而不是那份不在场的 spec(见 01 章)。

3. 核心原理:触发是怎么发生的(先建立直觉)

这一节回答最容易被忽视的问题:Claude 凭什么决定翻哪张卡?

思路。 Claude 的 available_skills 列表里只有每个 skill 的 name + description(L1)。它只读 description 就要拍板要不要消耗成本去翻开正文。所以 description 不是简介,而是触发器。

一个反直觉的关键点: Claude 只在自己搞不定的任务上才翻 skill。像「读一下这个 PDF」这种一步到位的简单活,即使 description 完美匹配也可能不触发——因为模型直接用基础工具就办了。复杂、多步、专门的任务才会稳定触发。

来源:skills/skill-creator/SKILL.md「How skill triggering works」(约 396-401 行)。这条直接决定了「怎么写测试用例」——简单 query 是坏测例。

由此推出两条 description 写法铁律(详见 02 章与 03 章):

要点出「做什么」+「什么时候用」:所有「何时触发」的信息都进 description,不要散落在正文。
要适当『推』一点:Claude 目前倾向漏触发(undertrigger)。所以与其写「构建仪表盘的方法」,不如写「……只要用户提到 dashboards / 数据可视化 / 内部指标,哪怕没明说『仪表盘』,都要用本 skill」。

来源:skills/skill-creator/SKILL.md「Write the SKILL.md → description」(约 67 行)。skills/claude-api/SKILL.md 的 description 是把这条用到极致的实例(见 03 章)。

4. 阅读地图(往下读哪章)

按「由浅入深」推荐顺序:

01-anatomy-progressive-disclosure.md —— 想真正搞懂「一个 skill 是什么」就先读这章:文件夹结构、frontmatter 的真实校验契约(以 quick_validate.py 为准)、三级加载怎么落地、.skill 怎么打包。
02-skill-creator-eval-loop.md —— 想学「怎么造一个好 skill 并证明它真的更好」读这章:skill-creator 的草稿→测试→评测→迭代闭环,with_skill vs baseline 对照实验,description 触发率优化循环。
03-skill-gallery-patterns.md —— 想抄套路读这章:17 个 skill 反复出现的设计模式(脚本当黑盒、reference 按域拆、推式触发、共享 office/ 库、API 漂移表)。

5. 边界与局限(诚实)

spec 不在克隆内。 spec/agent-skills-spec.md 只是一行重定向链接;权威 frontmatter 规则要看代码(quick_validate.py),不是看这个文件。
触发不是确定性的。 是否翻开 skill 由模型即时判断,受任务复杂度、措辞、当前模型影响;没有「关键词必触发」的硬保证(skills/skill-creator/SKILL.md 约 396-401 行)。
部分 skill 是 source-available 而非开源。 docx/pdf/pptx/xlsx 四个是「可看源码、非开源」(README.md「About This Repository」),许可见各自 LICENSE.txt。
示范性质。 README 明示这些 skill「仅供演示/教学」,实际 Claude 行为可能与此不同(README.md「Disclaimer」)。

6. 横向对比(同 shelf 视角)

Skill 与同属 agent-frameworks 的两类东西容易混:

机制	它是什么	加载/触发方式	谁在仓库里
Agent Skill	文件夹 SOP + 工具箱	description 触发 + 三级渐进式披露	本仓库
MCP server	一个对外暴露工具的服务进程	客户端连接、按协议调用 tool	本仓库教你用 skill 去造 MCP(`skills/mcp-builder/`)
System prompt 注入	一段常驻提示	永远在上下文里	——

关键差异:skill 的卖点正是不常驻——L2/L3 用到才进上下文。这也是它和「把知识塞进系统提示」最本质的区别。

7. 代码地图(导航索引)

主题	文件路径	符号 / 锚点
frontmatter 真实校验契约	`skills/skill-creator/scripts/quick_validate.py`	`validate_skill`, `ALLOWED_PROPERTIES`
三级渐进式披露说明	`skills/skill-creator/SKILL.md`	「Progressive Disclosure」节
触发机制说明	`skills/skill-creator/SKILL.md`	「How skill triggering works」节
description 写法(推式)	`skills/skill-creator/SKILL.md`	「Write the SKILL.md」→ description
插件分组	`.claude-plugin/marketplace.json`	`plugins[].skills`
最小 skill 模板	`template/SKILL.md`	frontmatter `name`/`description`
安装/使用入口	`README.md`	「Try in Claude Code」节

1. 这是什么(零基础也能懂)​

2. 顶层全景(它大概怎么转)​

2.1 一个 skill 文件夹长什么样​

2.2 三级渐进式披露(整个系统的灵魂)​

2.3 主线:一次 skill 调用怎么走完​

2.4 仓库目录(部件一句话职责)​

3. 核心原理:触发是怎么发生的(先建立直觉)​

4. 阅读地图(往下读哪章)​

5. 边界与局限(诚实)​

6. 横向对比(同 shelf 视角)​

7. 代码地图(导航索引)​