如何创建Agent Skills：工具、测试与安装
简而言之。 从一项反复出现的任务开始，用
superpowers:writing-skills把它变成一个 Skill。创建过程中，测试有该 Skill 和没有该 Skill 时的场景，并验证SKILL.md的结构。然后在一批真实任务中使用这个 Skill。如果它始终有帮助，就通过 Skills 仓库或 Plugin 与团队分享。
创建你的第一个 Agent Skill 很简单。新建一个文件夹，在其中放入 SKILL.md 文件，写几条说明即可。
更难的是知道这个 Skill 是否真的有效。
Agent 必须在几十条其他说明中找到它，在正确的请求上调用它，忽略相似但不相关的请求，遵循它的说明，并产出比没有该 Skill 时更好的结果。
本指南涵盖完整周期的工具：创建、改进、验证、测试、安装和维护。
在实践中，Skill 是什么
Agent Skill 是一个文件夹，包含说明、参考资料，以及（如果需要）可执行脚本。只有一个文件是必需的：SKILL.md。
一个最小化的 Skill 如下所示：
开放的 Agent Skills 规范要求 name 和 description 字段。description 告诉 Agent 何时为当前任务读取完整的 Skill。
这很重要，因为 Skills 的加载方式如下：
- Agent 会看到可用 Skills 的名称和描述。名称始终会列出；当你有许多 Skills 时，Claude Code 可能会为了适应上下文预算而丢弃最少使用的 Skills 的描述。
- 描述帮助它决定是否读取某个特定的 Skill。
- Skill 被激活后，它会读取完整的
SKILL.md。 - 它只在需要时打开额外的
references/、scripts/和assets/。
Anthropic 称之为渐进式披露。它用于管理上下文：Agent 不需要在每个请求中都包含每个 Skill 的全文。它会读取相关任务的说明，并在需要时打开更长的参考资料。
Skill、AGENTS.md 还是 Plugin？
并非每条说明都应该成为 Skill。
为什么 Skills 一度开始取代 MCP 集成，以及后来发生了什么变化
大型 MCP 集成过去会把每个工具的描述加载到每个请求中。几个服务器就可能占据上下文窗口的很大一部分。这促使人们用包含 CLI 命令的 Skills 来替代狭窄的集成：Agent 只在需要时才读取这些说明。
现代的带延迟加载的工具搜索改变了这种权衡。未使用的 MCP 工具的描述不再必须包含在初始请求中：Agent 可以找到它需要的工具，并按需加载其描述。这使发现机制更像 Skills，不过它们的角色仍然不同：Skill 提供流程和知识，而 MCP server 执行外部操作或返回数据。
需要新 Skill 的一个好迹象：你第三次把同一份清单粘贴到聊天中，或向新会话解释同一个流程。
创建 Skills 的工具
1. Agent 本身
你不需要单独的生成器。Anthropic 的官方编写指南建议在普通 Agent 会话中从头到尾完成一项真实任务，然后让 Agent 把可重复的流程提取成一个 Skill。
作为起点，这比从零开始发明一个通用 Skill 更好。真实工作会很快让你看到：
- 你不断重复的上下文是什么；
- Agent 在哪里做出了错误决策；
- 哪些内容应该放在说明中，哪些内容作为脚本会更好；
- 你需要哪些示例和边缘情况。
你的初始请求可以很简单：
2. skill-creator 或 superpowers:writing-skills
有了草稿后，你可以使用官方 skill-creator。它帮助创建和编辑 Skills、构建测试场景、将结果与没有 Skill 的初始运行进行比较，并对两个版本进行盲测 A/B 比较。
从官方 Marketplace 安装：
安装后，你可以让 Agent：
对于创建 Skills，我推荐 Codex 和 superpowers:writing-skills。它的原则更严格：先给 Agent 一个没有该 Skill 的真实场景，并记录一个具体的失败；然后编写最小可用的 Skill，重复同一场景，并检查其行为是否改变。如果 Agent 在没有该 Skill 的情况下始终能正确完成任务，那么新 Skill 可能没有意义。
对于早期版本来说，这已经足够了。你不需要为一条还没用过两次的说明搭建 CI 系统。
三种不同的检查
“验证”这个词常常掩盖了三个不同的问题。
superpowers:writing-skills 增加了一个预备步骤：在没有该 Skill 的情况下运行一个场景，给 Agent 施加压力，并观察它在没有额外说明时如何表现。这是在测试前提本身。如果基线运行已经成功，那么该 Skill 没有增加任何东西；如果失败，你就能看到需要改变的具体行为。
1. 结构是否有效？
对于可移植的 Skill，使用开放规范的验证器：
它检查 frontmatter 和命名规则。
在 Claude Code 中，你可以这样验证项目 Skills：
或者验证用户级 Skills、agents 和 commands（这不会检查 settings 或 Hooks）：
根据 Claude Code 文档，验证器会发现 YAML、元数据和 Plugin 结构的问题。这会检查语法和 schema。成功的结果并不意味着 Agent 会在正确的时间选择该 Skill。
2. Skill 会触发吗？
在创建 Skill 时，把这项检查交给 superpowers:writing-skills。加入应该触发它的真实请求，以及听起来相似但不应该触发的请求。superpowers:writing-skills 会运行这些场景，并显示 Agent 是否在正确的时刻找到这些说明。
如果 Skill 没有触发，或在本不该触发时触发，就改进它的 description 并重复检查。如果它触发了但没有帮助，就重新审视主要说明和支持文件。
3. 结果改善了吗？
对于打包为 Plugin 的 Skill，Claude Code 有一个单独的测试工具（需要 Claude Code v2.1.269 或更高版本）：
Claude plugin eval 会在隔离会话中，分别在有和没有 Plugin 的情况下多次运行每个场景。评分器可以检查文本、工具调用、操作顺序、创建的文件，或由 LLM 评估的标准。WITH 和 W/OUT 之间的差异显示了 Plugin 的贡献，而不仅仅是基础模型完成任务的能力。
这对于团队会进行版本管理、共享或在关键流程中使用的 Skills 很有用。这些运行会进行真实的模型调用。默认情况下，每个场景在有 Plugin 时运行三次、没有 Plugin 时运行三次，因此一套测试既耗时又费钱。
有一个细节很重要：skill-creator 和 claude plugin eval 使用不同的测试格式。前者适合通过对话改进单个 Skill。后者更适合 Plugins、回归测试套件和 CI。
/skill-doctor 会告诉你什么
/skill-doctor 回答的是另一个问题：哪些 Skills 消耗上下文但很少被使用？
它会显示描述占用了多少上下文、哪些 Skills 从未被调用过，以及哪些 Plugins 有一段时间未被使用。这有助于从大型库中移除噪音。但 /skill-doctor 不会评估说明质量，也不能替代行为检查。
如何在项目中安装 Skill
最简单的选择是手动添加：
然后创建 .claude/skills/review-migration/SKILL.md 并提交该文件夹。该 Skill 会在该仓库的会话中加载。
对于需要在你所有本地项目中使用的个人 Skill：
在 monorepo 中，你可以把 Skill 放在 <package>/.claude/skills/。它会应用于该子树中的工作。
如果某个 Skill 发布在 Git 仓库中，并支持开放生态：
加上 -g 可将其全局安装，而不是安装到当前项目。
何时需要 Plugin 和 Marketplace
独立的 Skill 在一个仓库内运行良好。当你想要以下情况时，使用 Plugin：
- 将多个 Skills 作为一个包分发；
- 添加 agents、Hooks 或 MCP 配置；
- 拥有命名空间，例如
/database-tools:review-migration； - 对包进行版本管理和更新；
- 附加正式测试套件。
一个最小化的 Plugin 结构：
你可以在本地这样测试 Plugin：
要共享它，团队可以创建一个私有 Marketplace，在项目级别添加它，然后从那里安装 Plugin。官方 Marketplace 文档支持 GitHub 仓库、Git URL、远程 marketplace.json 和本地路径。
等效的 CLI 支持 user、project 和 local 范围。在 project 级别，配置会写入仓库，因此团队共享同一个 Plugin 来源。
安装前检查第三方 Skills
Agent 说明从未如此容易广泛传播。一个仓库和一条安装命令就可以把别人的 SKILL.md、脚本或整个 Plugin 放进数百个工作环境中。
Skill 会向一个有权访问文件和工具的 Agent 提供说明。Plugin 还可以包含 Hooks、MCP servers 和可执行脚本。在目录中受欢迎并不能自动使该代码安全。
安装前，请检查：
SKILL.md的内容以及对scripts/的每一处引用；allowed-tools和 shell 命令；- Plugin 内部的 Hooks 和 MCP 配置；
- 该 Skill 是否请求机密信息、不必要的权限或网络访问；
- 仓库所有者、许可证、变更历史和更新流程。
对于团队库，固定一个经过审查的版本，在 CI 中运行验证，并像更新其他依赖一样谨慎地更新 Skills。
无需额外基础设施的实用流程
对于你的第一个 Skill：
- 在没有该 Skill 的情况下完成一项真实任务。
- 记录基线结果：Agent 究竟在哪里失败或行为不一致。
- 让 Agent 提取可重复的流程。
- 写出三个应该触发该 Skill 的请求，以及三个相似但不相关的请求。
- 把该 Skill 放入
.claude/skills。 - 验证其结构。
- 在新会话中带着该 Skill 重复基线场景。
对于团队使用的 Skill：
- 添加更多真实场景。
- 将不稳定的步骤移到确定性脚本中。
- 将该 Skill 打包为 Plugin。
- 添加
claude plugin eval。 - 在 Skill 变更后以及切换到新模型后运行测试套件。
- 定期检查
/skill-doctor，并禁用你不使用的内容。
主要错误：测试文件，而不是行为
最弱的成功标准是：“Agent 读取了 Skill，而且它的答案看起来没问题。”
更好的问题是：
- Skill 是否在没有提到其名称的情况下触发？
- 它是否对相似但不相关的请求保持沉默？
- 与基线运行相比，它是否改善了结果？
- 它是否减少了重复解释？
- 你能在新会话中复现结果吗？
- 新版本是否修复了特定失败，同时没有破坏现有场景？
Skill 不是你写一次然后润色的文档。它是 Agent 工作流中可执行的一部分。像对待代码一样对待它：保持简短，在真实场景中测试，进行版本管理，不要把有效语法与正确行为混为一谈。
在实践中尝试
我们发布了一组用于生成有效单元测试的 Agent Skills，包括使用 JUnit 5、Mockito 和 AssertJ 的 Java。在你的项目中安装它，并在真实代码上试用。## 参考资料
- Claude Code —— 使用技能扩展 Claude
- Claude Code —— 使用评估测试插件
- Claude Code —— 创建插件
- Claude Code —— 插件市场
- Agent Skills 规范
- Anthropic —— 技能编写最佳实践
- Anthropic —— 管理工具上下文
- Anthropic —— skill-creator
- Superpowers —— writing-skills
- Vercel Labs —— skills CLI
分享此页面
链接已复制
发现错误，或有内容要补充？在 GitHub 上编辑此页面
[LOADING...]
作者
Maks Danylenko
Maks Danylenko 在 Mavka 从事 AI 开发者工具方面的工作，其中包括开源的 Agent Skills——用于教会编码智能体使用 JUnit 5 和 Mockito 为 Java 编写高效的单元测试。