Agent Skills 概述

什么是 Agent Skills

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

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

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

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

渐进式披露：L1/L2/L3

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

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

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

Token 节省

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

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

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

实际工作流程

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

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

为渐进式披露而设计

描述是你的搜索索引

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

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

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

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

A helpful checklist for content.

跨层级分配内容

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

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

技能类型

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

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

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

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

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

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

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

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

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

元技能的关键设计规则：

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

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

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

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

多技能组合

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

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

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

技能生态

社区仓库

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

存储约定

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

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

参考资料

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

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