Agent Skill 完全指南：它是什么、怎么来的、为什么管用

Posted on In Word count in article: 6.9k Reading time ≈ 25 mins.
从 SKILL.md 的结构到渐进式披露的原理，讲清楚 Agent Skill 是什么、2025 年如何诞生并成为开放标准、 和 CLAUDE.md、MCP、Hook、Subagent 有什么区别，以及怎么写好一个 skill。

写于 2026-10-01。事实部分主要依据 Anthropic 官方文档与工程博客、agentskills.io 规范、Claude Code 文档；个别生态数据来自第三方文章，文中已标明。凡是"我的理解/推断"也会明说。

0. 一句话版本

Skill 是一个文件夹，里面有一份写给 AI 的"工作手册"（SKILL.md），可选地附带脚本和参考资料。AI 平时只看到每份手册的"标题 + 一句话简介"，判断当前任务相关时，才把整份手册读进来照着做。

没有任何神秘的东西：不是微调模型，不是插件系统，不是新的模型能力。它本质上是一套"按需把文字塞进上下文"的约定，聪明之处全在"按需"二字。

如果你只想记三件事：

  1. 形态：目录/SKILL.md，顶部 YAML（name + description），下面是 Markdown 正文。
  2. 机制：渐进式披露（progressive disclosure）——先给目录，用到再翻页，再用到再翻附录。
  3. 意义：把"人类专家脑子里的流程知识"变成可复用、可版本管理、可分享的文件，而不用每次重新写一大段提示词。

1. 先看一个我自己的真实例子

我这个博客仓库里就有 5 个 skill，放在 .agent/skills/：

.agent/skills/
├── blog-maintain/SKILL.md          # 改笔记后：检查 → 修复 → 发布
├── blog-cat-agent/SKILL.md         # 看板喵 + Worker 的维护
├── blog-verify-ui/SKILL.md         # 本地预览 + 浏览器验证
├── hexo-dependency-audit/SKILL.md  # npm 依赖审计
└── use-secrets-safely/SKILL.md     # 安全使用密钥文件
.claude/skills/<name> -> ../../.agent/skills/<name>   # 符号链接，Claude Code 通过它发现

打开 use-secrets-safely/SKILL.md，顶部是：

---
name: use-secrets-safely
description: 用户把 API key/密码放在某个文件里让你用时……任何涉及密钥文件的任务都应先看这个 skill。
---

下面是 39 行的正文：七个步骤，每步给出具体的 grep/curl 命令。

现在对照一下 AI 实际发生了什么（本次会话的系统提示里就能看到）：

阶段 发生什么 占用上下文
会话开始 系统提示里列出所有 skill 的 name: description 一行行清单 每个 skill 一两行
我说"key 在 ~/Downloads/x.txt，帮我设上" AI 对照清单，发现 use-secrets-safely 的描述匹配 无变化
AI 调用 Skill 工具 39 行正文被读进对话 约几百 token
执行中 按步骤跑命令；如果有 scripts/ 就运行脚本，只有输出进上下文 只有输出

这就是 skill 的全部。 后面的章节只是在解释"为什么这样设计"和"这样设计的边界在哪"。

2. 为什么需要 skill：它解决的问题

2.1 大模型的两个先天局限

  1. 没有你的流程知识。 模型懂 PDF，但不知道"你们公司的报表模板"；懂 Hexo，但不知道"我的博客发布前要跑 tools/blog.py、有 ERROR 不能发"。
  2. 上下文窗口是稀缺资源。 把所有流程知识都塞进系统提示，既贵又会稀释注意力——指令越多，每条被遵守的概率越低。

2.2 此前的各种解法，各自的痛点

方案 做法 痛点
长系统提示 / 自定义指令 所有规矩写在一起，每次全量加载 越写越长；无关任务也付 token；难维护
复制粘贴提示词 每次手动贴 重复劳动；版本混乱；无法团队共享
RAG（检索增强） 向量库按相似度捞片段 捞的是片段不是流程；要搭基础设施；步骤顺序容易丢
微调 把知识训进权重 贵、慢、不可审计、更新要重训
自定义 GPT / Projects 绑定一批文件和指令 绑定在某个产品里，粒度粗（整个项目），不可组合
工具 / MCP 给模型"手"（能调接口） 解决"能做什么"，不解决"该怎么做"
CLAUDE.md / AGENTS.md 项目级常驻说明 常驻、全量加载，只适合"永远成立"的规矩

Skill 的定位正是填这条缝：既要按需加载（省上下文），又要是流程/手册而非碎片（可靠），还要纯文件（好版本管理、好分享）。

官方的比喻很准确：它像给新员工准备的入职手册——不需要新员工背下来，需要时翻到对应章节就行。

3. 来龙去脉：发展时间线

3.1 前史（2022–2025）：各种"给模型喂上下文"的尝试

这一段按我的知识整理，具体日期以公开记录为准，仅作脉络参考。

  • 2022–2023：提示工程、ChatGPT 插件（2023 初）、Function Calling（2023 年 6 月）。模型第一次能"调用外部能力"。
  • 2023 年 11 月：自定义 GPT。第一次把"指令 + 知识文件 + 工具"打包成可分享的东西，但绑死在 ChatGPT 产品里。
  • 2024 年：Claude Projects（项目级知识库）；MCP（Model Context Protocol）于 2024 年 11 月发布，给"模型接外部系统"定了开放标准。
  • 2025 年上半年：Claude Code 等命令行 coding agent 兴起。CLAUDE.md（项目常驻说明）、自定义 slash command（.claude/commands/*.md，一个 Markdown 就是一条可复用提示词）成为开发者的日常。同时 OpenAI 系推动 AGENTS.md 这类跨工具的项目说明约定。

此时已有的积木：常驻说明（CLAUDE.md）、手动触发的提示词（slash command）、外部工具（MCP）。缺的是：一份说明书，AI 能自己决定什么时候翻开，而且能带着脚本和资料一起走。

3.2 2025-10-16：Agent Skills 正式发布

Anthropic 在工程博客《Equipping agents for the real world with Agent Skills》中公开介绍。动机原文意思是：通用 agent 很强，但缺少领域专长与组织上下文，需要"更可组合、可扩展、可移植"的方式去装备它们。

首发内容：

  • 规范：目录 + SKILL.md + YAML 元数据 + 渐进式披露。
  • 预置技能：PowerPoint、Excel、Word、PDF 四个文档技能（claude.ai 上创建文件的能力背后就是它们）。
  • 自定义技能：Claude Code 里放进 ~/.claude/skills/ 或 .claude/skills/ 即可；claude.ai 里上传 zip；API 里通过 /v1/skills 上传。
  • 同期 Claude Code 网页版上线，也支持 Skills（第三方时间线汇总为 2025-10-20）。

一个有意思的点：官方明确说 PDF 技能的原型场景是——Claude 很懂 PDF，但没法直接操作 PDF 表单，于是把"怎么操作"写成脚本 + 说明，打包成技能。也就是说 skill 一开始就不只是文字，而是"文字 + 可执行代码"。

3.3 2025-12-18：开放标准 + 组织级管理

  • Anthropic 把规范独立发布到 agentskills.io，作为开放标准，并提供校验工具 skills-ref。
  • 同期补上组织管理（管理员统一下发/管理）、合作伙伴技能目录等"生命周期"功能。
  • 此后数周到数月，主流编码 agent 陆续支持同一格式：OpenAI Codex、Google Gemini CLI、GitHub Copilot、Cursor、JetBrains Junie 等（据第三方文章统计，到 2026 年 4 月已有 30+ 工具采用；"下载量/技能数量"一类数字各家说法不一，不要当精确数据）。
  • .agents/skills/ 成为跨工具的事实目录约定——这正是我仓库里把真身放 .agent/skills/、再给 Claude Code 做符号链接的原因（见 AGENTS.md）。

3.4 2026 年：成熟与融合

  • Slash command 并入 skill：Claude Code 文档现在明确写着"自定义命令已合并进 skill"。.claude/commands/deploy.md 仍能用，但 .claude/skills/deploy/SKILL.md 功能更多（可带支持文件、可控制谁能触发、可限制工具、可 fork 子代理）。一个 skill 既是"AI 自动翻开的手册"，也是"你敲 /名字 触发的命令"。
  • Claude Code 里的 skill 能力大幅扩展：参数、动态上下文注入、context: fork、paths 条件加载、描述预算与诊断命令（/skill-doctor）、嵌套目录发现等（详见第 6 章）。
  • API 层面：据 Claude Platform 发布说明的第三方汇总，Skills 与 /v1/skills 在 2026-08-19 脱离 beta。（单一来源，需要精确信息请查官方 release notes。）
  • 官方后续方向（来自 2025 年那篇博客）：继续完善创建/编辑/发现/分享的全生命周期；探索与 MCP 的互补关系；让 agent 自己创建、编辑、评估 skill——也就是把"一次成功的做法"沉淀成下次可用的能力。

3.5 时间线速览

2022-23  提示工程 / 插件 / Function Calling
2023-11  自定义 GPT（打包指令+知识，但产品内封闭）
2024-11  MCP：给模型接外部系统的开放协议
2025 H1  CLAUDE.md、slash command、AGENTS.md：项目级常驻说明与手动提示词
2025-10-16  ★ Agent Skills 发布（SKILL.md + 渐进式披露 + 文档技能）
2025-12-18  ★ 开放标准 agentskills.io + 组织级管理
2026 H1  多家 coding agent 跟进；slash command 并入 skill
2026-08  Skills API 脱离 beta（第三方汇总）

4. 一个 skill 长什么样

4.1 目录结构（agentskills.io 规范）

skill-name/
├── SKILL.md       # 必需：元数据 + 指令
├── scripts/       # 可选：可执行脚本（Python / Bash / JS …）
├── references/    # 可选：按需读取的参考文档
└── assets/        # 可选：模板、图片、数据文件

只有 SKILL.md 是必需的，其余目录只是推荐约定，你可以放任何文件。

4.2 SKILL.md 的 frontmatter

开放标准里的字段：

字段 必需 约束
name ✅ ≤64 字符；小写字母/数字/连字符；不能以连字符开头结尾，不能有连续 --；必须与目录名一致
description ✅ ≤1024 字符；要同时说清"做什么"和"什么时候用"
license 许可证名或随附文件
compatibility ≤500 字符；环境要求（需要 git/docker/联网等）
metadata 任意字符串键值对，给工具自定义用
allowed-tools 预批准工具列表（实验性，各实现不一）

Anthropic 自家平台额外限制：name 不能含 "anthropic"、"claude" 这类保留词。

我仓库 AGENTS.md 里写的"frontmatter 必须有 name，与目录同名，和 description"——正是这个规范。

4.3 正文

规范对正文没有格式限制，"写任何对 agent 完成任务有帮助的东西"。推荐包含：步骤、输入输出示例、常见边界情况。官方建议主文件控制在 500 行以内，更长的内容拆到 references/ 里，并且引用层级只做一层（SKILL.md → 参考文件，别再层层嵌套）。

4.4 好的 description 与坏的 description

# 好：说了做什么 + 什么时候用 + 含用户会说的关键词
description: Extracts text and tables from PDF files, fills PDF forms, merges PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or extraction.

# 差：太泛，AI 无从判断
description: Helps with PDFs.

我仓库里的写法也是同一思路，比如 blog-maintain："新增、修改、移动、删除 source/_posts 下的笔记……后使用：先跑检查再自动发布"——既有触发场景，又有动作概述。

5. 原理：为什么这样就管用

5.1 核心：渐进式披露（Progressive Disclosure）

这个词来自 UI 设计：先给用户最少的必要信息，需要时再展开细节。Skill 把它用在上下文管理上，分三层：

层级 何时加载 大致成本 内容
L1 元数据 会话启动，永远在 每个 skill 约 100 token name + description
L2 指令 skill 被触发时 建议 <5000 token SKILL.md 正文
L3+ 资源 正文里引用到、且确实需要时 用到前为 0 references/、assets/；脚本运行而非读取 
┌─────────────────────────── 上下文窗口 ───────────────────────────┐
│ 系统提示                                                          │
│   ├─ skill A: 一句话简介   ← L1，常驻，极便宜                       │
│   ├─ skill B: 一句话简介                                           │
│   └─ skill C: 一句话简介                                           │
│                                                                    │
│ 对话……                                                            │
│   └─ [触发 B] B 的 SKILL.md 全文 ← L2，只在相关时才进来              │
│        └─ [需要时] B/references/schema.md ← L3，再按需翻开          │
│        └─ [需要时] 运行 B/scripts/check.py → 只有输出进上下文        │
└────────────────────────────────────────────────────────────────────┘
        磁盘上的其余文件：不占一个 token

这带来三个直接好处：

  1. 装得起很多 skill：装 50 个，常驻成本也只是 50 个简介。
  2. 单个 skill 可以很大：一个 skill 里放整套 API 文档也行，没用到的文件零成本。官方的说法是"可打包内容实际上没有上限"。
  3. 脚本比让模型现写代码更省、更稳：脚本代码本身不进上下文，只有执行结果进；而且是确定性的，不会每次写得不一样。

5.2 "触发"是怎么发生的？

这是最容易被误解的地方。没有关键词匹配器，没有向量检索，没有路由模块。 机制很朴素：

  1. 宿主程序（Claude Code / claude.ai / API）启动时扫描 skill 目录，把每个 skill 的 name + description 拼进模型能看到的内容里（Claude Code 里是一个叫 Skill 的工具，工具说明里列着所有可用 skill）。
  2. 模型像做阅读理解一样，用自己的语言理解能力判断："用户这个请求，哪个 skill 的描述对得上？"
  3. 判断为相关，就调用 Skill 工具（或用 bash cat SKILL.md），宿主把正文返回给它。
  4. 模型读完正文，按里面的步骤继续干活。

所以：

  • description 就是路由规则本身，写得好不好直接决定触发率。这也是为什么官方反复强调"要写清什么时候用"。
  • 触发是概率性的，不是 100%。这是下面"局限"一章的根源。
  • 你也可以绕过判断，手动触发：Claude Code 里敲 /skill-name。

这是我的归纳而非官方原话：skill 机制把"选择该用哪个能力"这件事，从工程代码转移给了模型的语言理解。优点是不需要写任何路由逻辑、新增 skill 零成本；缺点是触发不够确定。

5.3 为什么 skill 必须配"文件系统 + 代码执行"

渐进式披露要成立，模型得有自己去翻文件的能力——能 cat 一个文件、能运行一个脚本。这就是为什么：

  • 在 API 上用 skill，需要同时开启代码执行工具（skill 住在沙箱容器里）。
  • 在 Claude Code 里天然成立（本来就能读写文件、跑命令）。
  • 官方原话：skill 在"模型能访问虚拟机/文件系统"的环境里运行，"像你为新同事整理的入职资料"。

换句话说，skill 是"agent + 文件系统"这个范式的产物。没有文件系统的纯聊天模型，就没办法按需翻页。

5.4 skill 内容进入上下文之后

以 Claude Code 为例（官方文档所述）：

  • 触发后，渲染好的 SKILL.md 作为一条消息进入对话，之后各轮一直留在上下文里（不会每轮重读磁盘）。所以它是"整个任务期间的常驻指令"，写法上应该是"每次编辑后都跑测试"，而不是"跑测试"这种一次性步骤。
  • 上下文压缩（compaction）时：被调用过的 skill 会重新附上，但每个只保留前约 5000 token，总预算约 25000 token。→ 最重要的规则写在最前面。
  • 同一个 skill 再次调用，渲染结果相同就只提示"已加载"，不重复塞入。

5.5 小结：它到底是什么、不是什么

是：磁盘上的文本 + 一套"何时、如何读进上下文"的约定。 不是： - 不是训练/微调——模型权重一点没变； - 不是代码插件——SKILL.md 本身不执行，只是被读；执行的是 skill 里引用的脚本，由 agent 通过 bash 跑； - 不是权限系统——skill 本身不赋予新能力，它只是教模型"用现有能力怎么做"（allowed-tools 可以预批准工具，但那是宿主的权限配置，不是 skill 魔法）。

6. 在 Claude Code 里，skill 多出来的本事

以下来自 Claude Code 官方文档。版本相关的细节变化较快，以 code.claude.com/docs/en/skills 为准。

6.1 放哪里 & 谁优先

位置 路径 范围
企业 托管设置目录 部署机器上的所有人（最高优先）
个人 ~/.claude/skills/<name>/SKILL.md 你机器上所有项目
项目 <repo>/.claude/skills/<name>/SKILL.md 当前仓库（可随 git 共享）
嵌套 <子目录>/.claude/skills/… Claude 访问到该子目录时才加载（适合 monorepo）
插件 <plugin>/skills/… 命名空间为 /插件名:技能名
内置 Claude Code 自带 可被自定义同名覆盖

同名时：企业 > 个人 > 项目。

6.2 谁能触发：两个开关

配置 效果 典型用途
默认 AI 自动触发，你也能 /名字 手动触发 大多数 skill
disable-model-invocation: true 只有你能手动触发，AI 不会自己用 有副作用的操作：部署、提交、发消息
user-invocable: false 只有 AI 能用，不出现在 / 菜单 纯背景知识

→ 我的 ./run.sh 发布流程如果想"必须我点头才发"，就是 disable-model-invocation 的典型场景（目前我选择让 AI 自动发布，见 AGENTS.md 规矩 1，所以保持默认即可）。

6.3 其他常用 frontmatter

字段 作用
when_to_use 追加的触发说明（与 description 合计上限约 1536 字符）
argument-hint / arguments 参数提示 / 命名参数，正文里用 $ARGUMENTS、$0、$name 引用
allowed-tools / disallowed-tools 仅在本 skill 生效的那一轮预批准/移除工具
model / effort 本 skill 使用的模型 / 思考力度
context: fork + agent 在隔离的子代理里执行（看不到当前对话历史，适合大量读文件的调查型任务）
paths glob 条件：只有操作匹配的文件时才自动加载
hooks 触发时注册钩子

6.4 动态上下文注入

正文里写 !`git diff HEAD`，这条命令会在模型看到内容之前由本机执行，输出直接替换占位符。这样 skill 一加载，模型看到的就是"当前真实状态"而不是"请你去运行 git diff"。命令失败（非零退出）会中止整个 skill 调用。

6.5 实用特性

  • 实时变更检测：改 SKILL.md 当场生效，无需重启（新建顶层 skills 目录除外）。
  • 描述预算：所有 skill 的描述列表占上下文的约 1%。超了就按"最近最少用"压缩描述，名字永远保留。/skill-doctor、/context 可以查成本。可把不常用的设成 name-only。
  • 堆叠触发：/skill1 /skill2 arg 可以连着用。

7. 开放标准与生态

  • 规范：agentskills.io，由 Anthropic 发起并开源；有参考校验库 skills-ref validate ./my-skill。
  • 互通的关键：只要遵守"目录 + SKILL.md + 两个必需字段"，同一个 skill 理论上能被不同 agent 读取。各家在扩展字段（如 Claude Code 的 context: fork）上不同，所以规范里 compatibility、metadata、allowed-tools(实验性) 这类字段就是留给差异的。
  • 目录约定：.agents/skills/（跨工具）与 .claude/skills/（Claude Code）。我仓库的做法——真身放 .agent/skills/，.claude/skills/ 放符号链接——就是为了"一份文件，多个 agent 都能读"。
  • 来源：Anthropic 官方仓库 anthropics/skills（含开源示例，如 Claude API 技能）、社区仓库、技能市场/注册表。数量增长很快，但质量参差，见安全一章。

8. 和相邻概念的区别（最容易混的部分）

解决什么 何时加载 谁触发 能带代码 典型例子
系统提示 / 提示词 一次性指令 立即 你 否 "用中文回答"
CLAUDE.md / AGENTS.md 项目永远成立的规矩与背景 会话开始，全量 自动 否 "改完博客要发布""密钥不进仓库"
Skill 某类任务的流程与资料 按需，分层 AI 判断或你 / 是 blog-maintain、use-secrets-safely
Slash command（旧） 手动触发的提示词模板 你敲时 你 否 已并入 skill
MCP 让模型连接外部系统/数据 工具定义常驻（可能很大） AI 调用 是（服务端） 连 GitHub、数据库
Subagent（子代理） 隔离上下文做子任务 派发时 AI/你 是 Explore、Plan
Hook 必须发生的确定性动作 事件触发 系统，不靠模型判断 是 每次写文件前跑 lint
Plugin 把以上各种打包分发 安装时 — 是 内含 skills + MCP + hooks

几句话理清：

  • CLAUDE.md vs Skill：前者是"宪法"（永远生效，所以要短），后者是"各科手册"（用到才翻，可以长）。我的 AGENTS.md 里"项目规矩"属于前者；"怎么发布、怎么验证 UI"属于后者——而且 AGENTS.md 里用一张表把 skill 指出来，正是"宪法里放目录，细节放手册"。
  • MCP vs Skill：MCP 给模型新的手（能调什么接口）；Skill 教模型怎么用手（什么顺序、注意什么）。两者互补——官方也说在探索二者的配合。
  • Hook vs Skill：Skill 是"建议"，靠模型遵守，可能漏；必须每次都发生的事（比如"有 ERROR 不许发布"如果要做到 100%）应该用 hook 或脚本强制。官方排障建议里也是这个思路。
  • Skill vs Subagent：Skill 是知识，默认在当前对话里生效；Subagent 是隔离的执行者。两者可以结合：context: fork 让 skill 的内容成为子代理的任务。

9. 怎么写出好 skill

结合官方最佳实践与我仓库里已有的写法：

  1. description 是第一优先级。 写清 ① 做什么 ② 什么时候用 ③ 用户可能说的词。一个 skill 再好，描述写偏了就等于不存在。
  2. 正文像写给聪明但新来的同事。 给流程、给命令、给判断标准；别写模型本来就知道的常识。每一段都问：删掉它，AI 会犯错吗？ 不会就删。
  3. 把易变的、体量大的放到 references/，正文只放"主流程 + 指路"。正文 < 500 行。
  4. 能脚本化的用脚本。 确定性操作（校验、格式转换、批处理）写成 scripts/，正文只说"运行它"。我仓库的 tools/blog.py 就是这种思路。
  5. 最重要的规则写在最前面（压缩上下文时只保留前约 5000 token）。
  6. 一个 skill 只管一类任务。 别做"万能手册"，否则描述写不准、触发也不准。
  7. 给判断标准，不只给步骤。 如 use-secrets-safely 的"能不读就不读；读也只读遮住的形状"——原则 + 步骤，AI 遇到没写到的情况也能推理。
  8. 验证它真的被触发、真的被遵守。 用不同说法的提示词测；不触发就改描述；中途不遵守就把关键规则前置或改成 hook。
  9. 有副作用的 skill 加 disable-model-invocation，让人来按按钮。
  10. 迭代：每次发现 AI 在这类任务里反复犯同样的错，就把纠正写进对应 skill——skill 是"把经验沉淀成文件"的最佳容器。

10. 局限与风险（如实说）

10.1 能力局限

问题 原因 缓解
该触发时没触发 触发靠模型判断 description，是概率性的 优化描述；用 /名字 手动触发；关键规则放 CLAUDE.md
触发了但中途不遵守 skill 只是上下文里的文字，不是强制逻辑；上下文很长时可能被稀释 规则表述成"整个任务期间"；必须执行的用 hook/脚本
压缩后丢内容 重新附加时每个 skill 只保留前约 5000 token 重要的写前面；必要时重新触发
装太多，描述被截断 描述列表有约 1% 上下文的预算 精简描述；不常用的设 name-only；/skill-doctor 查成本
不跨产品同步 claude.ai、API、Claude Code 各自独立存放 各处分别上传；或用文件 + 插件分发
运行环境差异 API 沙箱无网络、不能装包；Claude Code 有完整本机网络 按目标环境设计脚本，用 compatibility 字段声明

10.2 安全风险（重点）

官方原话的核心：把 skill 当作安装软件来对待。

  • skill = 指令 + 代码。恶意 skill 可以引导模型调用工具、执行脚本、外传数据；
  • 会拉取外部 URL 的 skill 风险更高——抓回来的内容本身可能带提示注入，而且依赖的外部内容可能随时间变化；
  • 只用自己写的或来源可信的；第三方 skill 要逐个文件审计（SKILL.md、脚本、图片、资源），留意意料之外的网络请求、文件访问；
  • 企业版可以对上传的自定义 skill 做内容扫描（不覆盖 API 上传的）。
  • Skill 不在零数据保留（ZDR）范围内：定义与执行数据按标准留存政策处理。

对我的博客：我的 5 个 skill 是自己写的、不拉外部内容，风险低；以后从网上装别人的 skill 前，务必先读一遍。

11. 回到这个博客：现状评价与建议

现状做得对的地方：

  • 结构合规：每个 skill 都是 <name>/SKILL.md，名字与目录同名，描述有触发场景。
  • "AGENTS.md 放常驻规矩 + 表格指向 skill"——正是渐进式披露的实践。
  • 真身放 .agent/skills/、符号链接到 .claude/skills/——跨 agent 兼容。
  • 每个 skill 都只有 40–60 行，远低于 500 行建议。

可以考虑的改进（都是可选的）：

  1. 把"必须发生"的约束从 skill 提升为强制机制：例如"检查有 ERROR 不得发布"，现在靠 blog-maintain 的文字约定 + run.sh；run.sh 里如果已经 exit 1 拦截就最稳。
  2. 有副作用的 skill 评估是否加 disable-model-invocation：目前我明确选择"改完自动发布"，所以保持现状合理；但如果以后某个 skill 涉及 wrangler secret put、强推之类，可单独加开关。
  3. 按需拆分 references/：如果 blog-cat-agent 将来变长，把 Worker 提示词、限流参数等拆到 references/，主文件留流程。
  4. 给每个 skill 加一两个"典型触发语"到 description，提升自动触发率（例如 blog-verify-ui 加"帮我看看页面""截图确认"之类用户会说的话）。
  5. 定期用 /skill-doctor 看哪些 skill 从不被触发，描述该改还是该删。

12. 术语表

术语 含义
Skill / Agent Skill 目录 + SKILL.md 构成的可复用能力包
SKILL.md skill 的入口文件：YAML 元数据 + Markdown 指令
frontmatter 文件顶部 --- 包裹的 YAML 部分
Progressive disclosure（渐进式披露） 分层按需加载：元数据 → 正文 → 资源
触发（trigger / invoke） skill 正文被读进上下文的时刻，可由 AI 判断或用户手动 /名字
上下文窗口（context window） 模型一次能"看到"的全部文字，稀缺资源
压缩（compaction） 上下文过长时自动总结旧内容，skill 会被截断重附
MCP Model Context Protocol，模型连接外部工具/数据的开放协议
Subagent / fork 在隔离上下文中运行的子代理
Hook 在特定事件（如写文件前）由系统强制执行的动作，不依赖模型判断
Plugin 把 skills、MCP、hooks 等打包分发的单位
AGENTS.md / CLAUDE.md 项目级常驻说明，永远加载

附：参考来源

  • Anthropic 工程博客：Equipping agents for the real world with Agent Skills（2025-10-16 发布，2025-12-18 更新）
  • Claude 平台文档：Agent Skills 概览
  • 开放标准规范：agentskills.io/specification
  • Claude Code 文档：Use Skills in Claude Code
  • 官方示例仓库：github.com/anthropics/skills
  • 第三方时间线与生态统计（仅作参考，数字请自行核实）：Verdent 时间线、noqta：30+ 工具采用

关于可信度的说明：第 3.1 节"前史"和第 8 章的对比表是我基于已有知识的整理；第 3.2–3.3 节、第 4–6 章直接依据上面列出的官方/规范来源；"Skills API 2026-08 脱离 beta"和"30+ 工具采用"来自第三方，单一来源，未经官方页面交叉验证。

延伸阅读：[[AI Agent/MCP 完全指南：它是什么、怎么来的、为什么管用|MCP 完全指南]]——skill 教模型"怎么做"，MCP 给模型"能做什么"，两篇合起来才是完整的 Agent 能力栈。