effective-agent-skills

高效的 Agent Skills

---

1. 什么是 Agent Skills

Agent Skill 是一个文件夹，其中包含一个 SKILL.md 文件（YAML frontmatter + Markdown 指令），以及可选的子文件夹，用于存放 Agent 按需加载的脚本、参考资料和资源。

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code (CLIs, validators, helpers)
├── references/       # Optional: detailed docs loaded only when needed
└── assets/           # Optional: templates, fonts, static files

Agent Skills (agentskills.io) 是一项开放标准。文件夹和 SKILL.md 格式可移植；调用控制等可选行为则可能因客户端而异。

---

2. 为什么使用 Skills

Skills 将流程性知识和上下文打包起来，以便重复使用：

• 上下文效率 — 仅在相关时加载指令
• 可重复性 — 多步骤流程成为可审计的工作流
• 可组合性 — 多个 Skills 可根据任务在运行时组合
• 可移植性 — 同一组文件可在不同供应商和界面中使用

---

3. 工作原理 — 渐进式披露

分为三个加载级别：

级别 1 — 发现（每个 Skill 约 100 个 token，始终位于上下文中）： Agent 首先会看到 name + description，以判断该 Skill 是否适用。

级别 2 — 激活（少于 5,000 个 token，匹配时加载）： 请求匹配时，Agent 会读取完整的 SKILL.md 正文。

级别 3 — 执行（无上限，按需进行）： Agent 会按需读取参考资料（references/foo.md）或运行脚本（scripts/validate.py）。运行脚本不一定要将其源代码加载到上下文中。

只有加载内容时，捆绑文件才会占用上下文。

---

4. SKILL.md 的结构

---
name: skill-name
description: What this skill does AND when to use it. Include trigger phrases the user will say.
---

# Skill Name

## Quick start
[Minimal working example]

## Workflow
[Step-by-step procedure with checklists]

## Output format
[What the user/agent should expect back]

## Advanced
[Link to references/ for rarely-needed detail]

Frontmatter 约束：

• name 必须使用小写字母和连字符，长度为 1–64 个字符，且必须与父文件夹名称完全一致
• 避免在 frontmatter 中使用 < 和 >（它们可能注入系统提示词）
• 无效的 YAML 会导致加载失败，且不会显示任何提示
• 绝不要在未加引号的 description 中写入 : （冒号 + 空格） — 严格的 YAML 解析器（例如 Pi 的解析器）会将其判定为嵌套映射并拒绝（“Nested mappings are not allowed in compact mappings”），尽管宽松的解析器（Claude Code）可以接受。如果句子中间需要冒号，请将整个值用单引号括起来，并将内部的撇号加倍：description: 'Differentiator: finds gaps in the user''s knowledge.'

仅手动调用因客户端而异

disable-model-invocation: true 不属于核心 Agent Skills 规范。这是 Claude Code 和 VS Code/Copilot 支持的客户端扩展。在这些客户端中，将其放入 SKILL.md frontmatter 可阻止自动调用，同时保留显式调用功能。

OpenAI Codex 在 Skill 内使用单独的文件 agents/openai.yaml：

policy:
  allow_implicit_invocation: false

若要在 Claude Code、VS Code/Copilot 和 Codex 之间共享仅手动调用的 Skill，请同时包含两种配置。切勿假设某个客户端专属的 frontmatter 字段适用于所有 Agent Skills 实现；请查阅各目标客户端的文档，并在每种运行环境中测试隐式调用。

---

5. 两种设计理念

模式 A — 能力原语（工具封装器）

Skill 是确定性 CLI 或脚本的轻量封装器。逻辑由代码实现。SKILL.md 教 Agent 如何调用它。

• 新增：新能力（搜索、电子邮件、浏览器、API 访问）
• 可靠性依托于：shell 工具，而非提示词
• 典型长度：30–80 行，主要是命令示例
• 适用情形：瓶颈在于“Agent 无法执行 X”

模式 B — 流程原语（认知规范）

Skill 编码了 Agent 应遵循的方法论。纯提示词工程 — 无需脚本。

• 新增：结构化工作流（TDD、代码审查、设计对齐、调试循环）
• 可靠性依托于：明确的流程、检查清单和验证循环
• 适用情形：瓶颈在于“Agent 的输出质量或流程很差”

---

6. 如何编写高效的 Skills — 按此执行

编写用于技能选择的描述

Agent 在加载正文前会看到名称和描述。请说明技能的功能，以及哪些具体任务应该触发它。

• 尽量用一两句简短的话。1,024 个字符的限制是上限，不是目标。
• 将主要使用场景和重要术语放在前面；宿主可能会缩短描述。
• 点明用户实际会提到的任务、输入或文件类型。匹配意图，而不只是匹配关键词。
• 只有在能避免与相关技能混淆时，才说明适用边界。
• 将工作流步骤放在正文中。避免含糊的说法、包罗万象的描述和同义词列表。

模式："[功能]。适用于[具体任务或情境]。"

来源：Agent Skills · OpenAI。

保持 SKILL.md 精简

• 超过一定长度后，你通常是在用文档表达本该写进脚本或引用文件的逻辑。

优先使用 Bash，其次才是文字说明

优先使用带内联注释的具体命令示例，而不是冗长的文字说明。

将确定性逻辑放进代码

任何脆弱、重复，或容易因变化而出错的内容 → 写成脚本。只有需要判断的任务才使用 Markdown。

根据任务脆弱程度调整严格性（自由度）

根据错误操作的代价调整指令的严格程度：

• 多种方法都可行时，使用宽松的自然语言启发式方法（例如代码审查）。
• 有首选模式但允许变化时，使用伪代码或模板（例如报告格式）。
• 工作流脆弱、容易出错或对一致性要求高时，使用精确脚本和严格的步骤列表（例如迁移、文档修补）。

构建验证循环

明确说明“验证 → 修复 → 再次验证”的循环。

• 文档技能：交付前进行视觉质量检查
• 代码技能：完成前确保测试通过且没有类型错误
• 数据技能：输出前验证模式

操作前检查状态

不要假设准备工作已经完成。指示 Agent 先验证状态，再据此选择操作：

First check if X is configured: [command]
If not, walk the user through setup: [steps]

按需加载并明确指示

明确告知 Agent 在什么情况下读取每个引用文件：

For standard cases, follow the steps below.
For [specific edge case], read references/edge-cases.md first.

引用最多嵌套一层

直接在 SKILL.md 中链接引用内容；多层嵌套可能导致内容读取不完整或遗漏指令。超过 100 行的引用文件应添加目录。

说明输出格式

展示结构化输出示例，以便其他工具可靠地解析。

通过 --help 获取完整信息

在 SKILL.md 中展示常见操作；其他操作使用 tool --help。

组合基础能力，不要捆绑工作流

每项技能只专注于一种能力或领域；大型工作流应由多个专注的技能组合完成。

适用时引用成熟原则

引用 TDD、DDD 或红绿重构等成熟方法时，注明其来源，以便 Agent 和用户验证预期的方法。

将持久化产物用于跨会话记忆

技能可以在仓库文件（CONTEXT.md、ADR、决策日志）中保留持久上下文，供后续会话使用。

---

7. 应避免的做法——反模式

不要重新讲解模型已经掌握的内容

提供模型所缺少的上下文。跳过基础的 Python 或 Git 教程；让每段内容都有存在的价值。

不要加入面向人的文档

技能文件夹中不要放 README.md、CHANGELOG.md 或 INSTALLATION_GUIDE.md。技能是为 Agent 编写的。

不要编写含糊的描述

• 不佳：“一个有助于处理文档的技能”
• 良好：“填写 PDF 表单字段、提取表单数据并扁平化已填写的 PDF。适用于用户提到 PDF 表单、可填写表单或以编程方式填充字段的情况。”

不要捆绑库代码

如果需要解析库，请通过 npm/pip 安装。不要将源代码粘贴到技能中。

不要编写单体巨型技能

将捆绑设计、规划、实现、测试和部署的技能拆分开。

不要假设 Agent 会自行推断

对每个重要步骤都要明确说明。

• 不佳：“然后部署。”
• 良好：“运行 npm run deploy:staging，并等待 /healthz 返回 HTTP 200 后再报告成功。”

不要编写仅改变风格的变体

仅改变语气或格式的技能应放在用户偏好或系统提示词中，而不是技能中。

不要忽视失败模式

对于每个可能失败的步骤，都要说明如何识别失败以及该怎么做。

不要加入时效性信息

“截至 2024 年第四季度……”很快就会过时。通过脚本获取实时数据，或者省略。

不要使用绝对路径

始终使用相对路径。无论操作系统如何，路径分隔符都使用正斜杠。引用技能目录时使用运行时占位符。

不要轻信不熟悉的技能

技能可以运行代码、引导行为并泄露数据。使用前应审核脚本、参考资料、名称和访问范围；遵循下方的安全检查清单。

---

8. 编写工作流

1. 找出差距。 让 Agent 执行真实任务。它经常在哪里失败或需要重新提示？这就是技能候选。
2. 确定模式。 能力原语（需要新工具）还是流程原语（需要更好的方法论）？
3. 先起草描述。 说明用途和适用时机；只有在能避免可能的混淆时才添加边界。
4. 编写可用的最精简正文。 只有测试发现缺口时才添加内容。
5. SKILL.md 变得过长后，将详细内容移至 references/。
6. 测试触发。 使用真实请求和相近但不适用的请求，不要提及技能名称。确认技能正文确实已加载。
7. 测试执行。 明确调用技能。如果输出有误，就修正正文。
8. 对抗性测试。 让另一个 LLM 提问：“哪些边缘情况会导致此技能失效？”然后补上缺口。
9. 版本控制。 将技能视为代码。打标签、建分支并进行评审。

---

9. 测试与调试

• 确认实际激活。 检查运行时是否加载了 SKILL.md；YAML 有效或 Agent 自称已加载都不能作为证明。
• 激活错误或未触发。 检查发现和调用设置，然后调整描述范围和触发措辞。
• 执行失败 → 正文有问题。 添加明确步骤、示例或验证方法。
• 触发测试使用新会话。 有些客户端会在启动时对技能进行快照。
• 使用计划部署的最弱模型进行测试。 更强的模型能弥补技能描述含糊的问题；较弱的模型则会暴露这些问题。
• 双向测试。 包含真实请求，以及包含相同关键词但不应触发技能的相近请求。重复测试有歧义的案例，并测试新的提示词，以避免过度拟合。

---

10. 组合使用

Agent 可以组合多个技能来完成一项任务：

• 一种技能 = 一个关注点。 避免打包多个关注点。
• 定义技能间的接口。 如果技能 A 生成供技能 B 使用的产物，请说明其结构。
• 共享仓库级上下文。 AGENTS.md、CONTEXT.md 或 settings.json 等文件可以协调多个技能，无需显式交接。
• 将技能连接成有用的工作流，例如对齐 → 规格说明 → 构建 → 验证 → 重构。

---

11. 安全检查清单

安装任何第三方技能之前：

• 阅读文件夹中的每个文件
• 审核 scripts/，检查是否存在出站网络调用、超出预期范围的文件访问和命令执行
• 检查参考资料中是否包含提示注入（“忽略之前的指令……”）
• 确认技能名称没有仿冒热门技能
• 首先在沙盒环境中运行
• 固定到特定版本或提交，而不是使用 latest

---

12. 发布检查清单

发布技能前：

• Frontmatter 中的 name 与文件夹名称一致
• 描述简洁，并优先说明能力和具体触发条件
• 必要时明确区分相关技能的适用边界
• 技能文件夹内没有面向用户的文档
• 不包含时效性信息
• 仅使用相对路径
• 适用时，操作前先检查状态
• 记录验证流程
• 相关时记录输出格式
• 已使用弱模型和强模型进行测试
• 已测试能否正确触发并正确执行
• 技能只做一件事
• 能与相关技能无缝组合
• 已纳入版本控制