概述 - Zapvol Docs

什么是 Agent Skills

Agent Skills 是扩展 AI Agent 能力的模块化知识单元。每个Skill是一个包含 SKILL.md 文件（YAML frontmatter + Markdown 指令）的目录，以及可选的参考资料、模板和脚本子目录。

该格式遵循 agentskills.io 规范，这是一个被 30 多个 Agent 工具采用的开放标准 — 包括 Claude Code、Gemini CLI、GitHub Copilot、Cursor、JetBrains Junie 等。所有Skill使用相同的目录结构：

skill-name/
├── SKILL.md          ← YAML frontmatter + markdown 指令（必需）
├── references/       ← 风格指南、检查清单、规范（可选）
├── assets/           ← 模板和输出格式（可选）
└── scripts/          ← 可执行脚本（可选）

由于格式是通用的，为一个 Agent 工具编写的Skill可以在任何遵循该规范的工具中使用。Skill是可移植的、可共享的、可用 git 进行版本控制的。

为什么需要 Skills

需要做一个 Skill 的三个典型信号，任一出现都该考虑：

反复粘贴同一段 playbook — 每次开始某类任务，你都把同一段步骤 / 检查清单 / 风格指南复制到对话里。这是最直接的 Skill 信号：做成 Skill，agent 下次自己想得起来用，不再依赖你手动粘贴
系统提示词 / CLAUDE.md 在膨胀 — 原本只放”项目是什么”的事实性内容，慢慢被塞进了”在 X 场景下做 Y 步骤”这类程序性内容。系统提示词每次调用都付 token，程序越多基线越贵 — Skill 只在用到时才加载，把这部分按需化出去
同一套规则在多 agent / 多项目复用 — 一份”合规检查清单”在 5 个 agent 里都要用，复制 5 份必有 5 份漂移。Skill 是 单一来源 + 跨 agent 复用 的载体

以招聘行业为例，三个信号在实践中的具体表现：

信号 ① — 招聘人员每次写 outreach message，都从模板库复制同一个，再人工调整岗位 / 薪资 / 语气。把模板做成 Skill（如 outreach-senior-eng、outreach-passive-pm），agent 写新 message 时按候选人画像自动选用
信号 ② — 招聘 agent 的 system prompt 起初只放公司基本信息，后来逐步塞进了 GDPR 候选人数据合规（EU）、EEOC 不利影响检查（US）、各州 / 各国薪资透明度披露规则、拒信合规措辞（GDPR 第 22 条管自动化决策 + EEOC 管歧视性措辞，双重约束）— 这些都是程序性合规内容，应该拆成独立 Skill 按需加载
信号 ③ — 同一份”EEOC 不利影响检查清单”如果在 sourcing / screening / offer 三个阶段的 agent 里各复制一份，半年内必然出现 3 个互相漂移的版本。Skill 化后变成单一来源，谁更新谁负责

招聘只是一个示例 — 任何流程化 + 多角色 + 合规约束的行业（医疗、法务、金融客服、保险）都能套同样的模式：把反复使用的程序性内容做成 Skill。

Skill 不是”另一种 prompt 的容器”，而是把”何时加载”这一动作从静态拼接转成运行时决策的工具 — 这是它和”把 markdown 拼进 system prompt”的根本区别。下一节展开这个运行时决策的具体机制。

渐进式披露：L1/L2/L3

传统方式将所有内容打包到系统提示词中：合规规则、风格指南、API 参考、故障排查流程。当有十个Skill时，无论是否相关，每次调用都会消耗数千 token。

渐进式披露通过三级加载解决这个问题，每级仅在需要时获取：

L1 — 元数据（每个Skill约 100 token）：SKILL.md frontmatter 中的 name 和 description 字段。启动时为所有Skill加载。这是 Agent 用来判断相关性的”菜单”。
L2 — 指令（建议 < 5,000 token）：完整的Skill正文。仅当 Agent 判定某个Skill与当前任务相关时才加载。
L3 — 资源（按需加载）：references/、assets/ 或 scripts/ 中的文件。仅当Skill指令引用它们时才加载。

Token 节省

以一个拥有 10 个Skill（每个平均 1,000 token）的 Agent 为例：

方式	每次调用的 Token	加载时机
单体式系统提示词	~10,000	每次调用，所有Skill
渐进式披露	~1,000 基线	L1 始终加载；L2/L3 按需

基线上下文减少约 90%，且需要时完整功能随时可用。

实际工作流程

三个层级对应三个 Agent 动作：

发现（L1）— Agent 看到所有可用Skill的轻量列表。每条仅包含名称和描述。Agent 扫描列表判断哪个Skill匹配当前任务。
激活（L2）— Agent 加载所选Skill的完整指令。包括分步指导：做什么、按什么顺序、有什么约束。
深度引用（L3）— Agent 按指令要求加载特定的参考文件。风格指南、检查清单、模板 — 只加载当前步骤需要的文件。

为渐进式披露而设计

描述是你的搜索索引

SKILL.md frontmatter 中的 description 字段是最重要的一行。它是 Agent 的搜索索引 — 如果描述模糊，Agent 就不会在该用时激活这个Skill。

好的描述 — 包含匹配用户意图的具体关键词：

SEO optimization checklist for blog posts. Covers title tags,
meta descriptions, heading structure, keyword placement,
and readability best practices.

差的描述 — 模糊、没有触发词：

A helpful checklist for content.

跨层级分配内容

内容类型	应该放在	原因
Skill身份 + 触发条件	L1（frontmatter）	Agent 需要这些来判断相关性
分步工作流	L2（指令）	每次Skill激活时加载一次
详细参考资料	L3（references/）	按步骤加载，保持 L2 精简
输出模板	L3（assets/）	仅在生成时需要

核心原则：将细节下沉。如果指令超过几百字，将详细知识移到 references/，让指令指向它。Agent 只在实际需要特定文件时才支付 L3 的 token 开销。

Skill类型

Skill从简单的内联定义到自扩展的Meta Skill，形式多样。每种类型使用相同的 SKILL.md 格式，但在存放位置、共享方式和功能上有所不同。

类型	来源	可复用性	最适合
内联	代码（配置对象、字典）	单个 Agent	简单检查清单、稳定规则
文件化	本地目录（SKILL.md + 子目录）	任何遵循规范的 Agent	需要参考文档的复杂Skill
外部	社区仓库	跨 Agent 可移植	他人已经写好的Skill
Meta Skill	内联 + L3 资源	自扩展	按需生成新Skill

内联Skill将知识直接嵌入代码。适用于不会被复用的小型项目特定规则。

文件化Skill存放在独立目录中，包含 SKILL.md 和可选的 references/、assets/、scripts/ 子目录。目录名必须与 frontmatter 中的 name 字段匹配。设计上将知识分为 L2（告诉 Agent 执行哪些步骤的指令）和 L3（每步的详细参考资料）。

外部Skill是来自项目外部的文件化Skill — 通常来自社区仓库。由于所有Skill遵循 agentskills.io 规范，任何人编写的Skill都能在任何兼容的 Agent 中使用。工作流：查找、下载到 skills/ 文件夹、审查、加载。

Meta Skill教会 Agent 如何生成新的 SKILL.md 文件。配备Meta Skill的 Agent 具备自扩展能力：它可以在运行时编写新的Skill定义来扩展自身能力。

Meta Skill的指令（L2）定义生成有效 SKILL.md 文件的规则 — 命名约定、frontmatter 要求、指令结构。其引用（L3）包含 agentskills.io 规范本身和一个可用的示例Skill。

当被要求创建新Skill时，Agent 会：

加载Meta Skill指令
通过 L3 引用读取规范和示例
按照规范生成完整的 SKILL.md
输出可直接保存的文件内容

Meta Skill的关键设计规则：

名称必须为 kebab-case，最多 64 个字符
描述不超过 1024 个字符，包含具体的触发关键词
指令应清晰、分步骤
细节放入 references/ — SKILL.md 保持在 500 行以内

生成的Skill遵循同一套 agentskills.io 规范 — 它们能在任何兼容的 Agent 工具中使用。随着时间推移，Meta Skill创建新Skill，这些Skill被测试和优化，最好的提交到团队Skill库 — 一个由 Agent 驱动的能力构建飞轮。

skill/
  SKILL.md            # 指令：生成有效 SKILL.md 文件的规则
  references/
    specification.md  # agentskills.io 规范
    example-skill/    # 可供学习的示例Skill

内容设计模式（Tool Wrapper、Generator、Reviewer、Inversion、Pipeline），请参阅设计模式页面。

多Skill组合

当 Agent 可以访问多个Skill时，它能自主决定加载哪些。L1 元数据列表充当菜单 — Agent 根据任务组合Skill，无需显式编排。

例如，被要求”写一篇博客引言并确保 SEO 友好”时，Agent 可以并行加载 blog-writer 和 seo-checklist 两个Skill — 无需被告知要加载两个。L1 描述提供了足够的上下文来判断两者都相关。

同样重要的是负面案例：当被问到一个不具备的能力时，设计良好的 Agent 会检查 L1 列表并回复没有匹配的Skill。不产生幻觉，不假装具备不存在的能力。

Skill生态

社区仓库

仓库	领域
skills.sh	社区市场（86,000+ 安装量）
google-gemini/gemini-skills	官方 Gemini API 最佳实践
vercel-labs/agent-skills	React、Next.js、部署模式
supabase/agent-skills	Postgres 优化指南
anthropics/skills	生产级文档Skill
awesome-claude-skills	100+ 按领域分类的Skill

存储约定

项目级（<project>/.agents/skills/）— 团队共享的Skill，随代码库管理
用户级（~/.agents/skills/）— 个人Skill，跨所有项目使用

Skill可用 git 进行版本控制。团队可以维护共享的Skill库，标签化发布，并加载到任何遵循规范的 Agent 中。随着Meta Skill生成的新Skill被测试和优化，Skill库在无需人工编写的情况下持续增长 — 一个由 Agent 驱动的能力构建飞轮。

接下来读什么

按你的角色分流：

想学如何写一个 Skill → 设计模式（5 种结构模板）+ 编写指南（起草 → 测试 → 迭代的作者循环）
想把 Skill 机制集成进自己的 agent 系统 → 集成指南（顶层架构选择、7 个核心决策、自动进化飞轮）

参考资料

Agent Skills 规范 — 定义 SKILL.md 格式的开放标准
什么是 Agent Skills？ — agentskills.io 的概念概述

本系列内容改编自 Lavi Nigam 的 Agent Skills 系列文章。