写在前面

如果你最近在用 Claude Code、Cursor、GitHub Copilot 这些 AI 编程工具，你大概已经感受到了一个问题：AI 很聪明，但它常常缺乏你项目的上下文。它不知道你的 API 长什么样、你的团队用哪套代码规范、你的部署流程有哪些坑。

Anthropic 在 2026 年推出了一个开放标准来解决这个问题，叫做 Agent Skills。我最近花了一些时间研究这个东西，发现它的设计思路确实很漂亮——简单、轻量、但解决了一个真实的痛点。这篇文章就来系统地聊聊它到底是什么、怎么用、以及我自己的一些实践心得。

一、Agent Skills 到底是什么

一句话概括：Agent Skills 是一种给 AI Agent 灌入专业知识和工作流程的标准化格式。

它的核心载体极其简单——一个文件夹，里面放一个 SKILL.md 文件。这个文件包含元数据（名字和描述）以及详细的指令，告诉 Agent 在遇到特定任务时应该怎么做。文件夹里还可以选择性地放脚本、参考文档、模板等资源。

my-skill/
├── SKILL.md          # 必须：元数据 + 指令
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：参考文档
├── assets/           # 可选：模板、资源文件
└── ...               # 任意其他文件或目录

它解决的核心问题是：Agent 越来越强大，但往往没有做好实际工作所需的上下文。Agent Skills 把程序性知识、团队规范、项目特定的上下文打包成可移植的、可版本控制的文件夹，Agent 按需加载。

二、为什么需要它

你可能会问：我直接在 CLAUDE.md 或者 .cursorrules 里写规则不行吗？当然可以，但 Agent Skills 解决了几个更深层的问题。

2.1 领域专业知识的封装

把特定领域的专业知识——从法律审查流程到数据分析流水线到演示文稿格式——封装成可复用的指令和资源。一个写好的 Skill 可以在你的团队里传递，新人拿来就能用。

2.2 可重复的工作流

把多步骤的复杂任务变成一致的、可审计的流程。不再是每次都靠 Agent 自由发挥，而是有一套标准的执行路径。

2.3 跨产品复用

这是 Agent Skills 最大的野心：写一次，到处用。 目前已经有超过 30 个 AI 产品支持了这个格式，涵盖了几乎所有你能想到的主流工具。

三、谁在用

Agent Skills 的生态已经相当庞大了。截至目前，支持这个格式的产品包括（但不限于）：

IDE 和编辑器： Cursor、VS Code（通过 GitHub Copilot）、TRAE（字节跳动）、Kiro（AWS）

终端 Agent： Claude Code、Gemini CLI、OpenAI Codex、Mistral Vibe、OpenCode、Roo Code

平台和框架： GitHub Copilot、Spring AI、Databricks Genie Code、Snowflake Cortex Code、Laravel Boost

专用 Agent： Junie（JetBrains）、Firebender（Android 开发）、Goose（Block）、Factory、Qodo

换句话说，无论你用的是 Anthropic、OpenAI、Google、还是 Mistral 的模型，无论你在 IDE 里还是终端里工作，大概率都能用上 Agent Skills。

四、三阶段加载机制

Agent Skills 的设计里有一个非常聪明的机制，叫做 渐进式披露（Progressive Disclosure）。Agent 加载 Skill 分三个阶段，逐步拉入更多细节：

第一阶段：发现（Discovery）。 Agent 启动时，只读取每个 Skill 的 name 和 description 字段。这大概只占 100 个 token 左右。这一步的目的是让 Agent 知道"我手头有哪些技能可以用"，但不加载任何具体指令。

第二阶段：激活（Activation）。 当用户的任务匹配了某个 Skill 的描述，Agent 才读取完整的 SKILL.md 正文。推荐控制在 5000 token 以内。

第三阶段：执行（Execution）。 Agent 按照指令执行任务，在需要时才加载 scripts/、references/ 等额外文件。

这个设计的好处是：Agent 可以同时拥有很多 Skill，但上下文窗口不会被撑爆。只有真正用到的 Skill 才会占用 token。

五、SKILL.md 的完整规范

一个 SKILL.md 文件由 YAML 前置元数据和 Markdown 正文两部分组成。

5.1 前置元数据（Frontmatter）

必填字段：

name：Skill 的标识名。最多 64 个字符，只能用小写字母、数字和连字符，不能以连字符开头或结尾，不能有连续连字符，且必须和父目录名一致。

description：描述这个 Skill 做什么、什么时候该用它。最多 1024 个字符。这是 Agent 决定是否激活这个 Skill 的唯一依据，所以非常重要。

可选字段：

license：许可证信息。

compatibility：环境要求。最多 500 字符。比如"需要 Python 3.14+ 和 uv"或"需要 git、docker、jq 以及网络访问"。大多数 Skill 不需要这个字段。

metadata：任意键值对，用于存储规范之外的附加属性，比如作者和版本号。

allowed-tools：空格分隔的工具列表，声明这个 Skill 可以预授权使用哪些工具。这是一个实验性字段。

一个最小示例：

---
name: skill-name
description: A description of what this skill does and when to use it.
---

一个带可选字段的示例：

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

5.2 正文（Body）

YAML 元数据之后就是 Markdown 正文，也就是 Skill 的具体指令。格式没有限制，写任何能帮助 Agent 有效执行任务的内容就好。推荐包含：分步骤指令、输入输出示例、常见边界情况的处理方法。

需要注意的是：Agent 一旦决定激活 Skill，会把整个正文加载进上下文。所以主文件建议控制在 500 行以内，较长的参考内容应拆到 references/ 等独立文件中。

六、Quickstart：5 分钟创建你的第一个 Skill

来，我们动手做一个最简单的 Skill——一个掷骰子的 Skill。

在你的项目中创建以下文件：

.agents/skills/roll-dice/SKILL.md

注意：不同的 Agent 客户端读取 Skill 的目录不一样。VS Code / GitHub Copilot 默认在 .agents/skills/，Claude Code 默认在 .claude/skills/。内容格式是完全一样的。

文件内容如下：

---
name: roll-dice
description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.), roll dice, or generate a random dice roll.
---

To roll a die, use the following command that generates a random number
from 1 to the given number of sides:

```bash
echo $((RANDOM % <sides> + 1))
```

Replace `<sides>` with the number of sides on the die
(e.g., 6 for a standard die, 20 for a d20).

就这么多——一个文件，不到 20 行。三个部分各司其职：name 是标识符，必须和文件夹名一致；description 告诉 Agent 什么时候该用这个 Skill；正文是 Agent 激活后要遵循的具体指令。

然后你可以直接在对话中问 Agent "Roll a d20"，Agent 会识别到这个 Skill，读取指令，执行命令，返回一个 1 到 20 之间的随机数。

七、写好 Skill 的最佳实践

创建 Skill 不难，但写出真正好用的 Skill 需要一些技巧。

7.1 从真实经验出发，而不是让 AI 凭空生成

一个常见的错误是直接让 LLM 生成一个 Skill，完全依赖它的通用训练知识。结果就是模糊、泛泛的流程——"妥善处理错误"、"遵循认证最佳实践"——而不是你项目中真正需要的具体 API 模式、边界情况和团队规范。

有效的做法是从真实的工作中提取。你可以先和 Agent 完成一个真实任务，在过程中提供纠正和偏好，然后把可复用的模式提炼成 Skill。关注：哪些步骤有效、你在哪里纠正了 Agent 的方向、输入输出长什么样、你提供了哪些项目特定的上下文。

另一种方式是从已有的项目资料中合成。好的素材包括：内部文档和操作手册、API 规范和配置文件、代码审查评论、版本控制历史中的补丁和修复、真实的故障案例及其解决方案。

7.2 通过真实执行来迭代

Skill 的初稿通常都需要打磨。拿真实任务跑一遍，然后把结果——所有结果，不只是失败的——反馈到优化过程中。即使只做一轮"执行-然后-修订"都能显著提升质量，复杂领域通常需要好几轮。

一个关键建议：去读 Agent 的执行轨迹，而不只是最终输出。 如果 Agent 在无效步骤上浪费时间，常见原因包括：指令太模糊（Agent 尝试了好几种方法才找到对的）、指令不适用于当前任务（但 Agent 还是照做了）、给了太多选项却没有明确默认值。

7.3 精打细算你的上下文

一旦 Skill 激活，它的全部内容会和对话历史、系统上下文、其他活跃的 Skill 一起挤在上下文窗口里。你的 Skill 里的每一个 token 都在和窗口里的其他内容争夺 Agent 的注意力。

加 Agent 不知道的，省 Agent 已知道的。 聚焦于没有你的 Skill Agent 就不知道的东西：项目特定的规范、领域特定的流程、不显而易见的边界情况、要使用的特定工具或 API。你不需要解释什么是 PDF、HTTP 怎么工作、数据库迁移是什么意思。

对每一段内容问自己："没有这条指令，Agent 会做错吗？"如果不会，就删掉。如果不确定，就测试一下。

7.4 控制的精细度要匹配任务的脆弱度

给 Agent 自由，当多种方法都可行且任务容错性高时。解释为什么比给出僵硬的指令更有效——理解目的的 Agent 能做出更好的上下文相关决策。

要具体要严格，当操作脆弱、一致性重要、或必须遵循特定顺序时。比如数据库迁移，就应该给出精确的命令，并注明"不要修改命令或添加额外参数"。

7.5 提供默认值，而不是菜单

当多种工具或方法都可行时，选一个默认的，然后简要提及替代方案，而不是把它们作为平等选项列出来。

// 不好——太多选项
你可以用 pypdf、pdfplumber、PyMuPDF 或 pdf2image...

// 好——明确的默认值加逃生通道
使用 pdfplumber 进行文本提取。
对于需要 OCR 的扫描版 PDF，改用 pdf2image 配合 pytesseract。

7.6 记录踩过的坑（Gotchas）

很多 Skill 中价值最高的内容就是一个"踩坑列表"——那些违反合理假设的、环境特定的事实。这不是泛泛的建议（"妥善处理错误"），而是具体的纠正：

## Gotchas

- users 表使用软删除。查询必须包含 WHERE deleted_at IS NULL，
  否则结果会包含已停用的账户。
- 用户 ID 在数据库中是 user_id，在认证服务中是 uid，
  在计费 API 中是 accountId。三者指向同一个值。
- /health 端点只要 Web 服务器在运行就返回 200，
  即使数据库连接断了也是。用 /ready 来检查完整的服务健康状态。

当 Agent 犯了一个你不得不纠正的错误时，就把它加到 Gotchas 里。这是迭代改进 Skill 最直接的方式。

八、description 字段的优化

Skill 只有被激活才有用。description 字段是 Agent 决定是否加载 Skill 的唯一机制。描述不够好 = Skill 不会在该触发时触发，或者在不该触发时乱触发。

8.1 写法原则

用祈使句。 把描述写成对 Agent 的指令："Use this skill when..." 而不是 "This skill does..."。Agent 在决定是否行动，所以告诉它什么时候该行动。

聚焦用户意图，而非实现细节。 描述用户试图达成什么，而不是 Skill 内部怎么运作。

宁可写得"霸道"一点。 明确列出 Skill 适用的场景，包括用户没有直接点名该领域的情况："even if they don't explicitly mention 'CSV' or 'analysis.'"

保持简洁。 几句话到一小段就够了。规范的硬性限制是 1024 个字符。

看一个前后对比：

# 优化前
description: Process CSV files.

# 优化后
description: >
  Analyze CSV and tabular data files — compute summary statistics,
  add derived columns, generate charts, and clean messy data. Use this
  skill when the user has a CSV, TSV, or Excel file and wants to
  explore, transform, or visualize the data, even if they don't
  explicitly mention "CSV" or "analysis."

8.2 系统化测试触发率

Agent Skills 的文档提出了一个相当严谨的方法来优化 description：设计大约 20 条测试查询（一半应该触发、一半不应该触发），然后多次运行每条查询，统计触发率。

其中最有价值的测试用例是近似但不该触发的——和你的 Skill 共享关键词或概念，但实际需要的是不同的东西。比如对于一个 CSV 分析 Skill，"写一个 Python 脚本读取 CSV 并把每行上传到 Postgres"就是一个好的反面用例——涉及 CSV，但任务是数据库 ETL，不是分析。

文档还建议把查询集拆成训练集（60%）和验证集（40%），避免过拟合。整个优化循环是：评估 → 识别失败 → 修订描述 → 重复。通常 5 轮迭代就够了。

九、在 Skill 中使用脚本

Skill 不只是文字指令，还可以捆绑可执行脚本。

9.1 一次性命令

当已有的包就能满足需求时，可以直接在 SKILL.md 中引用，不需要 scripts/ 目录。很多语言生态都提供了运行时自动解析依赖的工具：

# Python（uvx）
uvx ruff@0.8.0 check .

# Node.js（npx）
npx eslint@9 --fix .

# Go
go run golang.org/x/tools/cmd/goimports@v0.28.0 .

关键是锁定版本，确保命令行为一致。

9.2 自包含脚本

当需要可复用逻辑时，可以在 scripts/ 中放一个脚本，把依赖声明在脚本内部。比如 Python 支持 PEP 723 格式的行内依赖声明：

# /// script
# dependencies = [
#   "beautifulsoup4",
# ]
# ///

from bs4 import BeautifulSoup

html = '<html><body><h1>Welcome</h1></body></html>'
print(BeautifulSoup(html, "html.parser").select_one("h1").get_text())

然后用 uv run scripts/extract.py 一条命令搞定——自动创建隔离环境、安装依赖、运行脚本。类似的方案在 Deno、Bun、Ruby 中也都有。

9.3 为 Agent 设计脚本的原则

Agent 运行脚本时，通过读取 stdout 和 stderr 来决定下一步做什么。几个关键的设计原则：

绝对不要交互式提示。 Agent 在非交互式 shell 中运行，无法响应密码框、确认菜单。阻塞在交互输入上的脚本会无限挂起。所有输入通过命令行参数、环境变量或 stdin 传入。

提供 --help 输出。 这是 Agent 了解脚本接口的主要方式。包含简要描述、可用参数、使用示例。

写有信息量的错误消息。 "Error: invalid input" 浪费一轮对话。改成 "Error: --format must be one of: json, csv, table. Received: xml" 就好多了。

使用结构化输出。 优先 JSON、CSV、TSV 等格式，而不是自由文本。数据发到 stdout，诊断信息发到 stderr，两者分开。

幂等性。 Agent 可能会重试命令。"如果不存在则创建"比"创建并在重复时失败"更安全。

十、评估 Skill 的输出质量

一个 Skill 在一次尝试中看起来能用，不代表它能可靠地工作。Agent Skills 的文档提出了一套完整的评估框架。

10.1 设计测试用例

每个测试用例有三部分：提示（现实的用户消息）、预期输出（什么算成功）、输入文件（可选）。从 2-3 个测试用例开始，不要在看到第一轮结果之前过度投入。变换表述、覆盖边界情况、使用真实的上下文（文件路径、列名、个人语境）。

10.2 AB 对照运行

核心方法是每个测试用例跑两遍：一次带 Skill，一次不带 Skill（或用旧版本）。这给你一个基线来对比。

10.3 编写断言

断言是关于输出应该包含什么的可验证声明。在看到第一轮输出之后再写——你往往不知道"好"长什么样，直到 Skill 跑过一次。好的断言是具体的、可观测的："输出文件是有效的 JSON"、"柱状图有标注的坐标轴"、"报告包含至少 3 条建议"。

10.4 评分和聚合

对每个断言评分 PASS 或 FAIL，并附上具体证据。然后聚合出整体的通过率、耗时、token 用量。关键指标是 delta——Skill 带来了多少提升、花了多少额外成本。一个增加 13 秒但提升通过率 50 个百分点的 Skill 大概率值得；一个翻倍 token 用量但只提升 2 个百分点的 Skill 可能不值。

10.5 迭代循环

把失败的断言、人工反馈、执行轨迹三者一起给 LLM，让它提出改进方案。重点是：修复应该针对底层问题而非具体用例（避免过拟合）、保持精简（更少但更好的指令往往优于详尽的规则）、解释原因（"Do X because Y tends to cause Z" 比 "ALWAYS do X" 更可靠）。

当你对结果满意、反馈持续为空、或迭代不再带来显著改进时，就可以停了。

十一、我的实践：给博客系统创建 Skill

说完理论，来点实际的。我自己的博客系统就用了 Agent Skills。

我的博客是 Nuxt 3 + FastAPI 的技术栈，部署在家里的 Mac mini 上。我给 Claude Code 写了一个 Skill，包含了博客 API 的完整文档——认证方式、文章的 CRUD 操作、分类和标签管理、评论系统、文件上传、SEO 端点，以及推荐的工作流程（比如"发布新文章"的标准步骤）。

有了这个 Skill，我可以直接用自然语言让 Claude 帮我写博客、发布草稿、管理分类和标签，而不需要每次都解释 API 接口长什么样。实际上，这篇文章本身就是在 Agent Skills 的辅助下发布的。

几点实践心得：

第一，Gotchas 部分是最有价值的。 比如我的博客 API 中，草稿列表需要认证、公开接口只返回已发布文章这些细节，Agent 第一次肯定不知道。写到 Gotchas 里后就再也不会出错了。

第二，推荐工作流极其有用。 "发布新文章"这样的多步骤操作，如果不给 Agent 一个标准流程（先查分类和标签 → 创建缺失的 → 生成 slug → 创建草稿 → 更新内容 → 发布 → 验证），Agent 每次的做法都不一样，质量也参差不齐。

第三，注意敏感信息。 如果 Skill 里包含 API Key 等敏感信息，要确保文件不会被提交到 Git。我就是把 .claude/skills/ 加到了 .gitignore 里。

十二、总结

Agent Skills 的设计哲学可以用一句话概括：给 Agent 上下文，而不是给它更强的能力。

Agent 的底层能力已经足够强了——它会写代码、会调 API、会分析数据。它缺的是你的上下文：你的 API 长什么样、你的团队怎么做事、你的项目有哪些坑。Agent Skills 用一个极其简单的格式（一个文件夹加一个 Markdown 文件）解决了这个问题，而且做到了跨产品通用。

如果你正在用任何 AI 编程工具，我建议你尝试为你最常做的任务创建一个 Skill。不需要很复杂——从一个具体的、你经常需要向 Agent 解释的工作流开始。你会发现，这比每次在对话中重复解释高效得多。

相关链接：

官方文档：agentskills.io

GitHub 仓库：github.com/agentskills/agentskills

示例 Skills：github.com/anthropics/skills

Discord 社区：discord.gg/MKPE9g8aUy

# ai

Agent Skills：给 AI Agent 装上专业技能的开放标准