创建 Agent Skills 的最佳实践

本指南旨在说明如何编写专业级的 Agent Skills（技能），如何使用 LLM 进行验证，以及如何保持精简的 Context Window。

这是一套关于创建 Agent Skills 的最佳实践浓缩指南。如需查阅完整文档，请参阅 Claude 官方文档。

若要评估你的 Skill 是否表现良好并防止回归，请查看 skillgrade。

Skill 的结构

每个 Skill 都必须遵循以下目录结构：

skill-name/
├── SKILL.md              # 必须：元数据 + 核心指令
├── scripts/              # 可选：执行逻辑的脚本
└── assets/               # 可选：模板或配置文件

使用 LLM 进行开发与验证

通过迭代方式编写 Skill，利用 LLM 来完善描述并测试逻辑。

优化元数据（Metadata）

首先，将你的 SKILL.md 的内容（YAML 部分）粘贴给 LLM：

我正在根据 agentskills.io 规范构建一个 Agent Skill。Agent 将完全基于下方的 YAML 元数据决定是否加载此 Skill。

name: angular-vite-migrator
description: Migrates Angular CLI projects from Webpack to Vite and esbuild. Use when the user wants to update builder configurations, replace webpack plugins with rollup equivalents, or speed up Angular compilation.

严格基于此描述：

1. 生成 3 个你确信 100% 应该触发此 Skill 的真实用户提示词。
2. 生成 3 个听起来相似但不应该触发此 Skill 的用户提示词（例如，将 React 应用迁移到 Vite，或者仅仅是更新 Angular 版本）。
3. 对该描述进行评估：是否过于宽泛？建议一个优化后的重写版本。

此外，向 Agent 分配任务，观察它是否触发了 Skill 的读取，并检查其思维过程。与 Agent 反复沟通，确定它为何选择（或未选择）特定的 Skill。

逻辑验证

确保你的分步指令是确定性的，不要强迫 Agent 针对缺失的步骤产生幻觉。

将完整的 SKILL.md 和目录结构提供给 LLM：

这是我 SKILL.md 的完整草稿以及支撑文件的目录树。

├── SKILL.md
├── scripts/esbuild-optimizer.mjs
└── assets/vite.config.template.ts

[在此处粘贴你的 SKILL.md 内容] 扮演一个刚刚触发了此 Skill 的自主 Agent。基于“将我的 Angular v17 应用迁移到 Vite”的请求，分步模拟你的执行过程。

针对每一步，写出你的内部独白：

1. 你具体在做什么？
2. 你正在读取或运行哪个具体的文件/脚本？
3. 标记所有“执行阻塞点（Execution Blockers）”：指出因为我的指令模糊而被迫猜测或产生幻觉的具体代码行（例如，如何将 Angular 环境文件映射到 Vite 的 import.meta.env）。

边缘情况测试

强迫 LLM 寻找 Web 工具中固有的漏洞、不支持的配置和故障状态。

要求 LLM 攻击你的逻辑：

现在，切换角色。扮演一名严苛的 QA 测试员。你的目标是破坏这个 Skill。 请针对边缘情况、故障状态或 SKILL.md 中缺失的 Fallback 机制，向我提出 3 到 5 个高度具体且具有挑战性的问题。重点关注：

• 如果 scripts/esbuild-optimizer.mjs 因为遗留的 CommonJS 依赖而失败怎么办？
• 如果用户的 angular.json 包含 Vite 不支持的高度自定义 Webpack 构建器（@angular-builders/custom-webpack）怎么办？
• 我是否对用户的 Node 环境做出了隐性假设？

暂时不要修复这些问题。只需提出带编号的问题并等待我的回答。

架构优化

LLM 往往倾向于将大型配置文件直接塞进主提示词中。利用这一步强制执行“渐进式披露（Progressive Disclosure）”原则，缩小 Token 占用空间。

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

根据我对上述边缘情况问题的回答，重写 SKILL.md 文件，严格执行“渐进式披露”设计模式：

1. 将主要的 SKILL.md 严格保留为高层级的步骤集合，使用第三人称祈使句命令（例如：执行 esbuild 脚本，读取 Vite 配置模板）。
2. 如果当前文件中存在密集的规则、大型的 vite.config.ts 模板或复杂的 angular.json 模式，请将其移除。告知我创建一个位于 references/ 或 assets/ 的新文件，并将 SKILL.md 中的文本替换为仅在需要时读取该特定文件的严格指令。
3. 在底部添加专门的“错误处理（Error Handling）”部分，纳入我关于 Webpack Fallback 和 CommonJS 解析的回答。