创建 Agent Skill 的最佳实践

本指南详细介绍了如何编写专业级的 Agent Skill、如何利用 LLM 进行验证，以及如何维持精简的上下文窗口（Context Window）。

本指南汇总了创建 Agent Skill 的核心最佳实践。如果您需要更详尽的文档，请参阅 Claude 官方文档。

如需评估您的 Skill 表现并防止回归，请查看 skillgrade。

Skill 的结构

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

skill-name/
├── SKILL.md              # 必需：元数据 + 核心指令
├── README.md             # 建议：Skill 的详细文档
├── scripts/              # 必需：执行逻辑（脚本、工具等）
├── assets/               # 可选：模板、配置文件、参考资源
└── references/           # 可选：大型文档、API 规范

编写 SKILL.md

SKILL.md 是 Skill 的核心，必须包含用于自动发现的 YAML 元数据以及操作流程。

1. 元数据（Metadata）

在文件顶部添加 YAML 代码块。这是 Agent 决定是否加载该 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.

2. 指令（Instructions）

保持指令简练，遵循“渐进式披露”（Progressive Disclosure）原则。只提供核心步骤，将复杂逻辑拆分到 assets/ 或 references/ 目录中。

---

使用 LLM 进行验证与优化

您可以利用 LLM 来测试、批判并完善您的 Skill 设计。以下是具体的验证工作流：

触发逻辑验证

首先，将您的元数据投喂给 LLM，验证其触发机制是否符合预期：

I am building an Agent Skill based on the agentskills.io spec. Agents will decide whether to load this skill based entirely on the YAML metadata below.

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.

Based strictly on this description:

1. Generate 3 realistic user prompts that you are 100% confident should trigger this skill.
2. Generate 3 user prompts that sound similar but should NOT trigger this skill (e.g., migrating a React app to Vite, or just updating Angular versions).
3. Critique the description: Is it too broad? Suggest an optimized rewrite.

此外，通过要求 Agent 执行相关任务来观察其思维链。通过与 Agent 对话，找出它为何（或为何不）选择某个特定 Skill 的原因。

逻辑验证

确保您的分步指令具有确定性，不要强迫 Agent 对缺失步骤进行幻觉推测。

将完整的 SKILL.md 和目录结构投喂给 LLM：

Here is the full draft of my SKILL.md and the directory tree of its supporting files.

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

[Paste your SKILL.md contents here] Act as an autonomous agent that has just triggered this skill. Simulate your execution step-by-step based on a request to Migrate my Angular v17 app to Vite.

For each step, write out your internal monologue:

1. What exactly are you doing?
2. Which specific file/script are you reading or running?
3. Flag any Execution Blockers: Point out the exact line where you are forced to guess or hallucinate because my instructions are ambiguous (e.g., how to map Angular environment files to Vite's import.meta.env).

边缘情况测试

强制 LLM 寻找 Web 工具中固有的漏洞、不支持的配置和失败状态。

要求 LLM 攻击您的逻辑：

Now, switch roles. Act as a ruthless QA tester. Your goal is to break this skill. Ask me 3 to 5 highly specific, challenging questions about edge cases, failure states, or missing fallbacks in the SKILL.md. Focus on:

• What if scripts/esbuild-optimizer.mjs fails due to a legacy CommonJS dependency?
• What if the user's angular.json contains heavily customized Webpack builders (@angular-builders/custom-webpack) that Vite doesn't support?
• Are there implicit assumptions I made about the user's Node environment?

Do not fix these issues yet. Just ask me the numbered questions and wait for me to answer them.

架构重构

LLM 经常倾向于将大型配置文件直接放入主 Prompt 中。利用此步骤实施“渐进式披露”设计模式，减少 Token 占用。

让 LLM 应用修正方案并重构 Skill：

Based on my answers to your edge-case questions, rewrite the SKILL.md file, strictly enforcing the Progressive Disclosure design pattern:

1. Keep the main SKILL.md strictly as a high-level set of steps using third-person imperative commands (e.g., Execute the esbuild script, Read the Vite config template).
2. If there are dense rules, large vite.config.ts templates, or complex angular.json schemas currently in the file, remove them. Tell me to create a new file in references/ or assets/, and replace the text in SKILL.md with a strict command to read that specific file only when needed.
3. Add a dedicated Error Handling section at the bottom incorporating my answers about Webpack fallbacks and CommonJS resolution.