创建智能体技能的最佳实践

本指南介绍了如何编写专业级别的智能体技能、使用大语言模型对其进行验证，以及如何保持简洁的上下文窗口。

本指南是一套高度浓缩的最佳实践，用于创建智能体技能。如果您需要更全面的文档，请参阅 Claude 的文档。

要评估您的技能表现是否良好并防止功能退化，请查看 skillgrade。

技能的结构

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

纯文本

skill-name/
├── SKILL.md              # 必需：元数据 + 核心指令（不超过500行）
├── scripts/              # 可执行代码（Python/Bash），设计为小型命令行工具
├── references/           # 补充上下文（模式、速查表等）
└── assets/               # 用于输出的模板或静态文件

• SKILL.md： 充当“大脑”。用于导航和高层次流程。
• References： 直接从 SKILL.md 链接。仅保持一层深度。
• Scripts： 用于处理脆弱或重复性操作，其中任何变化都可能引发错误。请勿在此处捆绑库代码；

优化 frontmatter 以提高可发现性

SKILL.md 文件中的 name 和 description 是智能体在触发技能之前唯一能看到的字段。如果它们没有针对可发现性进行优化且不够具体，您的技能将无法被识别。

• 严格命名规范： name 字段必须为 1–64 个字符，只能包含小写字母、数字和连字符（不允许连续连字符），并且必须与父目录名称完全一致（例如，名称为 angular-testing 的技能必须位于 angular-testing/SKILL.md 中）。
• 编写适合触发的描述： （最多 1,024 字符）。这是智能体用于路由的唯一元数据。以第三人称描述功能，并包含“负面触发条件”。
  • 不良示例： “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）： 明确指示智能体何时读取文件。在您明确指示之前，它不会看到这些资源（例如：“请参阅 references/auth-flow.md 以获取特定错误代码”）。
• 显式路径： 始终使用带有正斜杠 (/) 的相对路径，无论操作系统如何。

技能是为智能体设计的，而非人类。为了保持上下文窗口简洁并避免不必要的 token 消耗，请勿创建：

• 文档文件： README.md、CHANGELOG.md 或 INSTALLATION_GUIDE.md。
• 冗余逻辑： 如果智能体已经能够可靠地完成某项任务而无需帮助，则应删除相关指令。
• 库代码： 技能应引用现有工具，或包含小型的、单一用途的脚本。长期存在的库代码应放在标准仓库的 CLI 目录中。

使用具体的程序化指令而非散文

为 LLM 而非人类编写指令。

• 使用逐步编号： 将工作流程定义为严格的按时间顺序排列的步骤。如果有决策树，应清晰地绘制出来（例如：“第 2 步：如果需要源映射，请运行 ng build --source-map。否则，跳至第 3 步。”）。
• 提供具体模板： 智能体对模式匹配非常擅长。与其花费数段文字描述 JSON 输出应如何呈现，不如将模板放置在 assets/ 文件夹中，并指示智能体复制其结构。
• 使用第三人称祈使语气： 将指令表述为直接对智能体的命令（例如：“提取文本……”而不是“我将提取……”或“你应该提取……”）。

在技能文件中引用概念时，务必保持具体性和一致性。

• 使用一致的术语： 为特定概念选择一个统一的术语。
• 具体性： 使用最符合您所描述领域的专业术语。例如，在 Angular 中使用“template”这一概念，而非“html”、“markup”或“view”。

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

不要每次运行技能时都要求 LLM 从头开始编写复杂的解析逻辑或样板代码。

• 将脆弱或重复的任务下放： 如果智能体需要解析复杂的数据集或查询特定数据库，可以为其提供经过测试的 Python、Bash 或 Node 脚本，存放在 scripts/ 目录中供其运行。
• 优雅地处理边缘情况： 智能体依靠标准输出（stdout/stderr）来判断脚本是否成功。编写返回高度描述性、易于理解的错误信息的脚本，以便智能体能够准确地自我纠正，而无需用户干预。

验证指南

由于 LLM 将会使用您的技能，我发现确保其有用性的最佳方法就是与 LLM 合作。

对技能进行评估至关重要，以确保您所做的更改产生积极影响，且不会导致功能退化。一个流行的技能基准测试是 SkillsBench，它可以为您提供一些灵感。

在您起草技能的初始版本后，可以通过以下步骤来验证您的工作：

发现验证

代理会严格按照 YAML 前置元数据来加载技能。请单独测试 LLM 对您描述的理解，以避免误触发（例如，当该技能适用于 Angular 时却因 React 应用而被触发）。

将以下文本原封不动地粘贴到一个新的 LLM 对话中：

我正在根据 agentskills.io 规范构建一个代理技能。代理将完全依据下方的 YAML 元数据来决定是否加载此技能。

name: angular-vite-migrator
description: 将 Angular CLI 项目从 Webpack 迁移到 Vite 和 esbuild。当用户希望更新构建配置、用 rollup 等效插件替换 webpack 插件，或加快 Angular 编译速度时使用。

仅基于此描述：

1. 生成 3 条您 100% 确信应该触发此技能的真实用户提示。
2. 生成 3 条听起来相似但不应触发此技能的用户提示（例如，将 React 应用迁移到 Vite，或仅仅更新 Angular 版本）。
3. 评价该描述：是否过于宽泛？请提出优化后的改写建议。

此外，向代理提供预期会触发该技能的任务，并仔细检查其思考过程。与代理反复交流，明确它为何选择（或未选择）特定技能。

逻辑验证

确保您的步骤式指令具有确定性，且不会迫使代理凭空猜测缺失的步骤。

将您的整个 SKILL.md 文件及目录结构输入 LLM：

以下是我的 SKILL.md 完整草稿及其支持文件的目录结构。

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

[在此处粘贴您的 SKILL.md 内容] 请扮演刚刚触发此技能的自主代理，模拟执行过程，任务是将我的 Angular v17 应用迁移到 Vite。

针对每一步，请写出您的内心独白：

1. 您具体在做什么？
2. 您正在读取或运行哪份具体的文件/脚本？
3. 标记任何执行障碍：指出由于我的指令不够明确而不得不猜测或“幻觉”出答案的确切位置（例如，如何将 Angular 环境文件映射到 Vite 的 import.meta.env）。

边界场景测试

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

让 LLM 攻击您的逻辑：

现在请切换角色，扮演一位严苛的 QA 测试员。您的目标是“破坏”这个技能。 请就边界场景、失败状态或 SKILL.md 中缺失的回退机制，向我提出 3 到 5 个高度具体且具有挑战性的问题。重点关注：

• 如果 scripts/esbuild-optimizer.mjs 因遗留的 CommonJS 依赖而失败怎么办？
• 如果用户的 angular.json 包含大量自定义的 Webpack 构建器（如 @angular-builders/custom-webpack），而 Vite 又不支持这些配置，该如何处理？
• 我是否对用户的 Node 环境做出了一些隐含假设？

请先不要修复这些问题，只需依次提出上述问题并等待我的回答。

架构优化

LLM 经常会尝试将大型配置文件直接塞入主提示中。通过这一步骤，您可以实施渐进式披露策略，从而减少 token 消耗。

让 LLM 应用您的修复方案并重构技能：

根据我对您提出的边界场景问题的回答，重新编写 SKILL.md 文件，严格遵循渐进式披露的设计模式：

1. 保持主 SKILL.md 仅为高层次的步骤集合，采用第三人称祈使句形式（例如，“执行 esbuild 脚本”、“阅读 Vite 配置模板”）。
2. 如果文件中包含密集规则、大型 vite.config.ts 模板或复杂的 angular.json 模式等，将其移除。指示我在 references/ 或 assets/ 目录下创建新文件，并用一条明确的指令替代 SKILL.md 中的相关内容，仅在需要时才读取该文件。
3. 在底部添加专门的错误处理部分，结合我对 Webpack 回退机制和 CommonJS 解析问题的回答进行完善。

skills-best-practices 快速上手指南

本指南旨在帮助开发者创建专业级的 Agent 技能（Skills），优化 LLM 上下文窗口，并通过标准化结构确保技能的可靠性和可发现性。

环境准备

• 系统要求：支持 Linux、macOS 或 Windows（建议使用类 Unix 环境以获得最佳脚本兼容性）。
• 前置依赖：
  • 任意主流 LLM 接入环境（用于验证和运行技能）。
  • 基础命令行工具（Bash/Zsh）。
  • （可选）Python、Node.js 或 Go，用于编写 scripts/ 目录下的确定性脚本。
• 推荐工具：
  • 使用 skillgrade 进行技能评估和回归测试。

安装步骤

该工具并非传统软件包，而是一套文件结构规范。无需执行安装命令，只需在您的项目中按照以下标准创建目录和文件即可。

1. 创建技能根目录： 目录名称必须全小写，仅包含字母、数字和连字符（不能连续使用连字符）。

   mkdir angular-testing
   cd angular-testing
   

2. 构建标准目录结构： 在根目录下创建以下文件和文件夹：

   touch SKILL.md
   mkdir scripts
   mkdir references
   mkdir assets
   

3. 初始化核心文件： 在 SKILL.md 中写入符合规范的 YAML Frontmatter 和指令（详见“基本使用”）。

基本使用

1. 编写 SKILL.md (核心大脑)

SKILL.md 是技能的入口，必须包含优化的元数据以便 Agent 发现，并遵循“渐进式披露”原则以保持上下文精简。

示例内容 (angular-testing/SKILL.md)：

---
name: angular-testing
description: Creates and builds React components using Tailwind CSS. Use when the user wants to update component styles or UI logic. Don't use it for Vue, Svelte, or vanilla CSS projects.
---

# Angular Testing Skill Instructions

You are an expert agent specialized in Angular testing strategies.

## Workflow
Follow these steps strictly in order:

1. **Analyze Requirements**: Identify the component to be tested and the specific testing framework (Jest/Karma).
2. **Load References**: If specific error codes or schema definitions are needed, read `references/testing-schema.md`. Do not load this file unless explicitly required by the current step.
3. **Execute Scripts**: For repetitive setup tasks, run the deterministic script:
   - Execute `scripts/generate-test-boilerplate.sh` with the component name as an argument.
4. **Generate Output**: Use the template found in `assets/test-template.ts` to structure the final test file.

## Error Handling
- If `scripts/generate-test-boilerplate.sh` fails, check the stderr output. If it mentions "legacy dependency", advise the user to update their Node version.
- Do not hallucinate configuration steps. If a step is unclear, refer to `references/angular-cli-docs.md`.

## Constraints
- Keep instructions in the third-person imperative (e.g., "Run the script", not "You should run").
- Do not include library code here; reference existing tools or small CLI scripts only.

2. 添加辅助资源 (渐进式披露)

将大型配置、Schema 或模板移至子目录，仅在 SKILL.md 中指示 Agent 何时读取。

• references/: 存放 API 文档片段、Cheatsheets。
  • 规则：保持扁平结构，仅限一级目录（如 references/schema.md，禁止 references/db/v1/schema.md）。
• scripts/: 存放处理脆弱或重复任务的脚本（Python/Bash/Node）。
  • 规则：脚本必须输出清晰的人类可读错误信息，以便 Agent 自我修正。
• assets/: 存放输出模板、JSON Schema 或静态文件。

3. 验证技能 (Validation)

在部署前，利用 LLM 对技能进行三轮验证，确保其逻辑严密且触发准确。

步骤 A: 发现验证 (Discovery Validation) 将 SKILL.md 的 Frontmatter 部分发送给 LLM，提示如下：

"Based strictly on this description: 1. Generate 3 realistic user prompts that should trigger this skill. 2. Generate 3 similar prompts that should NOT trigger this skill. 3. Critique the description for breadth."

步骤 B: 逻辑验证 (Logic Validation) 将完整的 SKILL.md 和目录树发送给 LLM，要求其模拟执行：

"Act as an autonomous agent... Simulate your execution step-by-step... Flag any Execution Blockers where instructions are ambiguous."

步骤 C: 边界测试 (Edge Case Testing) 要求 LLM 扮演测试人员寻找漏洞：

"Act as a ruthless QA tester. Ask me 3 to 5 highly specific questions about edge cases, failure states, or missing fallbacks in the SKILL.md."

根据反馈迭代修改 SKILL.md 和脚本，直至逻辑无歧义且上下文占用最小化。