打造Agent Skills的最佳实践指南

本文详细介绍如何编写专业级 Agent Skills，利用大语言模型（LLM）对其进行验证，并有效控制上下文窗口以提升运行效率。

（Agent Skills是什么？通俗来说，它是教会AI助手执行特定任务的“操作手册”与“工具集”，例如让AI掌握React组件编写、数据库操作等专项能力。）

本文提炼了创建Agent Skills的核心最佳实践。如需查阅完整文档，请参考Claude官方文档。

Skill的标准目录结构

每个skill必须遵循以下目录结构规范：

skill-name/├── SKILL.md# 必需：元数据与核心指令（不超过500行）├── scripts/# 可执行脚本（Python/Bash），设计为小型命令行工具├── references/ # 参考文档（API文档、速查表等）└── assets/ # 输出模板与静态资源文件

• SKILL.md： skill的“核心中枢”，用于导航和描述高层级操作流程。
• References： 通过SKILL.md直接引用，注意仅存放单层文件结构。
• Scripts： 针对易出错或重复性高的操作——此类场景下任何变化都可能导致错误。请勿在此打包库代码。

优化frontmatter，提升skill的可发现性

SKILL.md文件frontmatter中的 name 和 description 是Agent在触发skill之前唯一能读取的字段。若未优化得足够清晰具体，你的skill将难以被有效识别。

（frontmatter是Markdown文件顶部由三个横线包裹的元数据区块，通常包含name、description等配置信息。）

• 严格遵守命名规范： name 字段长度须为1-64个字符，仅支持小写字母、数字和连字符（禁止连续连字符），且必须与父目录名称完全一致（例如 name: angular-testing 须存放于 angular-testing/SKILL.md）。

• 编写触发优化的描述： （最多1,024个字符）。这是Agent用于路由决策的唯一元数据。建议采用第三人称描述能力，并包含“反向触发词”（即什么情况下不适用）。
  • 不佳示例： “React技能。”（过于模糊）
  • 优秀示例： “使用Tailwind CSS创建和构建React组件。当用户需要更新组件样式或UI逻辑时使用。不适用于Vue、Svelte或原生CSS项目。”

渐进式披露与资源管理

仅在需要时加载信息，保持上下文窗口整洁。SKILL.md充当高层逻辑的“大脑”，将细节内容下沉至子目录。

• 保持SKILL.md精简： 主文件限制在500行以内，用于导航和主要流程。
• 使用扁平子目录： 将大块内容移至标准文件夹，文件仅存放一层深度（例如 references/schema.md，而非 references/db/v1/schema.md）。
  • references/：API文档、速查表、领域逻辑。
  • scripts/：确定性任务的可执行代码。
  • assets/：输出模板、JSON模式定义、图片。
• 即时加载（JiT）： 明确指示Agent何时读取文件。在你指明之前，Agent无法感知这些资源（例如 “查看 references/auth-flow.md 了解详细的错误码”）。
• 显式路径： 始终使用相对路径，并采用正斜杠（/），不依赖操作系统类型。

（JiT是Just-in-Time的缩写，意为“即时”或“按需”。这是一种编程中的常见策略——不一次性加载所有内容，而是等到真正需要时才获取，从而节省内存和处理资源。）

Skills是为Agent设计的，而非面向人类读者。为保持上下文窗口精简、避免不必要的token消耗，请勿创建：

• 文档文件： README.md、CHANGELOG.md 或 INSTALLATION_GUIDE.md。
• 冗余逻辑： 若Agent无需帮助即可可靠处理某任务，则删掉该指令。
• 库代码： Skills应引用现有工具，或包含小型、单一用途的脚本。长期维护的库代码应存放于标准仓库CLI目录中。

使用具体的程序化指令，而非散文式描述

为LLM编写指令，而非面向人类读者。

• 使用分步骤编号： 将工作流程定义为严格的时间顺序。如有决策树，清晰画出（例如 “步骤2：若需要source map，运行 ng build --source-map；否则跳至步骤3。” ）。
• 提供具体模板： Agent的模式匹配能力极强。与其用多段文字描述JSON输出格式，不如将模板放在assets/文件夹中，并指示Agent复制其结构。
• 采用第三人称祈使语气： 将指令框定为对Agent的直接命令（例如 “提取文本...” 而非 “我将提取...” 或 “你应该提取...”）。

在skill文件中引用概念时，需具体且一致。

• 使用一致的术语： 为特定概念选定单一词汇。
• 具体性： 使用你所描述领域中最具体、原生的术语。例如，在Angular中使用“模板（template）”而非“html”、“markup”或“view”。

为重复性操作打包确定性脚本

避免LLM每次运行skill时都从零编写复杂的解析逻辑或样板代码。

• 将易碎/重复的任务卸载出去： 若Agent需解析复杂数据集或查询特定数据库，为其提供一个存放于scripts/目录中的、经过测试的Python、Bash或Node脚本。
• 优雅地处理边界情况： Agent依赖标准输出（stdout/stderr）判断脚本是否成功。编写脚本时，应返回高度描述性、人类可读的错误信息，使Agent能准确自我纠正，无需用户介入。

验证指南

既然LLM会使用你的skills，确保其有效性的最佳方式是与LLM协作验证。

为skills准备评估（evals）至关重要，这样你才能确保改动带来正面效果，避免回退。一个流行的skill基准测试是SkillsBench，可为你提供参考。

（evals是evaluations的缩写，意为“评估”或“测试”。在AI领域，evals是一套用于衡量模型或系统表现的测试用例与标准，如同考试一般检验你的skill是否真正有效。）

完成skill初稿后，可通过以下步骤验证：

发现性验证

Agent严格依据YAML frontmatter加载skills。测试LLM在孤立环境下如何解读你的描述，以防止误触发（例如本应用于Angular的skill却在React项目中被触发）。

将以下内容原封不动粘贴至全新LLM对话中：

此外，使用你期望触发skill读取的任务提示Agent，并检查其思考过程。与Agent来回沟通，找出它为何选择（或未选择）特定skills。

逻辑验证

确保你的分步骤指令具有确定性，不会迫使Agent“脑补”缺失步骤。

将完整的 SKILL.md 和目录结构输入LLM：

（“脑补”在此指LLM的幻觉现象——当指令不够明确时，AI可能编造不存在的步骤或信息来填补空白。）

边界情况测试

引导LLM主动查找漏洞、不支持的配置以及web工具固有的失败状态。

让LLM“攻击”你的逻辑：

（QA是Quality Assurance的缩写，意为“质量保证”。QA测试员的工作如同“找茬游戏”，竭力发现软件或系统中的bug与漏洞。）

架构优化

LLM常试图将大型配置文件直接塞入主提示。通过此步骤强制实施渐进式披露，缩小token占用。

让LLM应用你的修复并重构skill：