学习 AI SDLC – 构建代理技能的完整指南

也许你会有这样的经历：本周你已经用同样的说明四次解释了 AI 模型。

你反复谈到你们团队是如何组织一份演示文稿的；部署前会运行哪些检查；为什么暂存数据库不是 README 中提到的那个。

每次你都要重新输入一次；每次，代理都能做得不错；但每次，下一次会话都要从零开始。

这就是 Agent Skills 要解决的问题。

一个 skill 是一个仅包含单个 Skill.md 文件的文件夹。代理在启动时读取一行摘要，仅在任务真正需要时才打开完整说明。只需编写一次解释，将其提交到代码旁边，团队中的每个代理即可随时访问并自动化任何乏味的任务。

该格式起源于 Anthropic，随后作为开放标准发布，如今它支持超过 45 种可与之配合使用的工具，包括 Claude Code、VS Code、GitHub Copilot、Cursor、Gemini CLI、Codex、Goose 和 JetBrains Junie。Google Antigravity 也支持它。一个文件夹，适用于所有工具。

使用 Agent Skills 自动化可重复任务

大多数指南会把十几个半成品示例散落在十几个小节里。这里，我们将从零开始构建一个真正的 agent skill，使其能够在所有 AI 工具中兼容。

我们将构建 恰好一个 skill，命名为 deck-builder，它是本文唯一的示例。它教会代理如何将模糊的请求如 “为我制作一个关于 Q3 迁移的演示文稿” 转变为真实的演示大纲，方法是 先头脑风暴，后编写幻灯片。

这种顺序正是重点。让任何模型生成演示文稿，它会立即开始制作第一张幻灯片。结果是十二张内容整齐但泛泛而谈的要点幻灯片，却从未明确演示文稿的目的 是什么。

擅长此事的人会采取不同的做法。他们会先询问在场的人是谁，想向观众传达的核心信息是什么，以及他们想使用的大纲或框架。随后，他们会基于心理模型开始制作演示文稿。

该 skill 最初只有 28 行 Markdown，十分钟即可写完。到最后，它将具备经过调校的描述、误报列表、捆绑的验证器、按需参考文件、评估套件以及干净的安全扫描。本指南中的每个想法都会在这个随之增长的同一文件夹中得到演示。

这里不需要任何账户、API 密钥或 PowerPoint。你只需把 skill 放入 skills 文件夹，它就会根据你创建的 skill 生成演示文稿。

目录

• 使用 Agent Skills 自动化可重复任务

• 先决条件

代理技能到底是什么

• 你的巨型系统提示为何失效

• 代理技能的令牌优化

• 技能的组成

• 十分钟内构建版本 1

• 在 VS Code 或 Claude Code 中运行

• 版本 2：让其每次触发

• 版本 3：编写能赚取令牌的主体

• 版本 4：捆绑一个检查工作的脚本

• 版本 5：将深层材料移开

• 技能存放位置及代理如何查找它们

• 技能 与 规则 与 MCP 与 钩子 与 插件

• 证明该技能确实有帮助

• 安装前先扫描

• 悄悄浪费令牌的错误

• 起飞前检查清单

• 关键要点

• 结论

Prerequisites

你不需要深入了解 AI 代理就能跟随本指南，但掌握一些基础知识会让示例更易于操作。

你应该能够熟悉使用 Markdown 文件、在项目目录中导航以及在终端运行简单命令。示例使用 Python 作为捆绑验证器，因此你的机器上还需要安装 Python 3.9 或更高版本。

在演练过程中，你将使用支持 Agent Skills 的 AI 编程客户端，例如 Claude Code、带有 GitHub Copilot 的 VS Code 或 Google Antigravity。该技能本身不需要账户、API 密钥或 PowerPoint。

这就是你所需的全部。我们将从一个单一的 SKILL.md 文件开始，然后随着工作流变得更有用且更可靠，逐步构建它。

代理技能到底是什么

一个技能是一个目录。其中有一个必需的文件，名为 SKILL.md。

该文件由两部分组成：顶部是简短的 YAML 块，下面是 Markdown 说明；其余内容均可选。

注意：在此文件夹中添加更多文件会消耗更多 token，因为上下文窗口会因无关或废弃文件而增大。

本指南结束时，deck-builder 将位于此处：

deck-builder/
├── SKILL.md                                
├── scripts/
│   └── validate_deck.py          
├── references/
│   └── narrative-patterns.md
└── evals/
    └── evals.json                

您需要安装 Python 来执行脚本。技能是一份包含特定目标的元数据和说明的 Markdown 文件。

使用这种格式的价值在于它所捕捉的内容：

• 代理无法猜测的专业知识：您的评审门槛、演示风格、幻灯片惯例、框架等等。

• 重复的工作流程：多步骤任务变成一致的程序，而非即兴发挥。

• 跨工具复用：一次构建，在任何兼容的客户端（Claude Code、VS Code 等）中运行。

效果最好的心智模型是一个 可执行的运行手册。把一个好的技能想象成你会在第一天交给一个聪明新手的文档：它解释了确切的工作流程，指出了常见的陷阱，为繁琐的部分提供了脚本，并展示了如何验证一切是否正常运行。

Why Your Giant System Prompt Stops Working

大多数团队一开始会把所有内容堆进一个始终开启的文件中：AGENTS.md、CLAUDE.md，或者代码中的系统提示。幻灯片惯例被塞进去，位于部署运行手册和风格指南之间。

当只有两个约定时，这没问题。但会因三个原因而失效。

1. It costs you on every single request

系统提示会在每次 API 调用时加载。在用户输入任何内容之前，二十份运行手册可能会达到数万个标记。

您在第一轮就要付出这个成本。在第四十轮时又要再付一次。即便对话与演示无关，您仍需承担这一开销。

2. Long context doesn't mean even attention

大的上下文窗口并不等同于在其上均匀分配注意力。

当重要的那行被埋在数千行无关内容中时，遵循指令的能力会下降。"在写幻灯片之前先进行头脑风暴" 在 2000 个标记的提示中会被可靠遵循。在 80000 个标记的提示中，主要观点会被跳过。加载更多上下文并不等同于被理解。

3. Prose can't enforce a procedure

让模型“检查大纲”，每次得到的检查结果都不同。有时很彻底，有时只是一句话的赞美。

散文会让代理可能做对的事情。只有脚本才能使其可验证。

渐进式披露可以解决前两个问题。我们将在版本 4 中添加的验证器可以解决第三个问题。

Token Optimisation for Agent Skills

代理分三个阶段加载技能。了解每个阶段的结束位置是保持技能高效的关键。

规范对此给出了具体数字。发现阶段每个技能的元数据大约为 100 个 token。激活时，正文建议上限为 500 行或 5,000 个 token。超过此范围的内容应放在 references/ 目录中。

激活不是一次性费用

这一细节改变了你编写技能的方式。激活不是在代理完成任务后就会消失的一次性成本。 一旦技能被激活，其说明将保持在对话中，并在会话剩余时间继续消耗上下文。

Claude Code 精确地记录了这一点：渲染后的 SKILL.md 以单条消息的形式进入对话，并且会一直保留到会话结束。该文件不会在后续轮次被重新读取。

这里有三个后果：

• 每一行都是持续性成本： 膨胀的正文会在第二十轮产生费用，而不仅仅是在触发它的那轮。

• 编写常驻指令，而非一次性步骤： 代理在整个会话期间看到的都是相同的文本。

• 压缩可能会驱逐你的技能： 当 Claude Code 压缩长对话时，它会重新附加每个技能的最近一次调用，在总共 25,000 token 的预算内保留每个技能的前 5,000 token，优先保留最近的。如果调用许多技能，最早的那些将被完全驱逐。

最后一点解释了人们常见的误解。当技能在会话中途似乎停止工作时，其说明未必已经消失。模型可能只是更倾向于另一种方法。在这种情况下，应加强技能的说明，或在上下文压缩后重新调用它。

数学概要

设 N 为你已安装的技能数量，T（下降）为单个技能的元数据成本，T（完整）为单个技能正文的成本，k 为任务实际打开的技能数量。

一次性加载全部内容：

$$C_{ ext{static}} = N imes T_{ ext{full}}$$

逐步加载：

$$C_{ ext{progressive}} = N imes T_{ ext{desc}} + k imes T_{ ext{full}}$$

$$Use\\ the\\ spec's\\ own\\ budgets: T_{desc} = 100\\ and\\ T_{full} = 5,000,\\ for\\ 50\\ skills\\ where\\ one\\ activates.$$

$$C_{ ext{static}} = 50 imes 5{,}000 = 250{,}000 ext{ tokens}$$

$$C_{ ext{progressive}} = (50 imes 100) + 5{,}000 = 10{,}000 ext{ tokens}$$

$$\\rho = 1 - \\frac{10{,}000}{250{,}000} = 0.96$$

可实现 96% 的减少，在任务相同且可用的五十项能力相同的情况下。

该公式也表明了它失效的地方。当 k 远小于 N 时，渐进式披露更有效，也就是说大多数技能保持关闭状态。如果每个请求都打开你目录的一半，那么你的技能范围过宽，你实际上重建了单体技能文件。保持 k 较小是一个设计目标。

技能的结构

前置信息

顶部的 YAML 块包含两个必需字段和四个可选字段。

字段	必需	规则
name	是	1–64 个字符。小写字母、数字、连字符。不能有首尾或连续的连字符。必须与文件夹名称匹配。
description	是	1–1024 个字符。说明技能的作用 以及 何时使用它。
license	否	许可证名称，或一个捆绑的许可证文件。
compatibility	否	最多 500 个字符。环境需求：产品、软件包和网络访问。
metadata	否	用于自定义工具的自由格式字符串映射。
allowed-tools	否	由空格分隔的预批准工具列表。该特性在规范中被标记为实验性，Claude Code 完全实现了它。请参见下方注释。

以下是 deck-builder 最终得到的内容：

---
name: deck-builder
description: >-
  Turn a request for a presentation into a slide outline. Brainstorm the
  audience, core message, and narrative arc first, then write slides. Use
  when someone asks for a deck, slides, a presentation, a readout, a board
  update, or a talk, including when they only say "put something together
  for Thursday" without naming a format.
license: Apache-2.0
compatibility: Requires Python 3.9+. No network access needed.
---

有两条规则容易被忽视，尤其是在你开始让技能在不同客户端之间可移植时。第一条是 name 字段：它不仅仅是一个标签。根据规范，它必须完全匹配父文件夹。因此，如果你的技能位于 deck-builder/SKILL.md，前置信息必须使用 name: deck-builder，而不是 name: deckBuilder。

第二条是 description 字段的限制。规范允许最多 1024 个字符，但一旦你为了在 Version 2 中获得更好的触发效果而调整描述，这个限制就很容易被超出。一些客户端更宽松，接受这些规则的变体，但这种灵活性可能导致可移植性问题。先按照严格的规范编写，你的技能在各处表现一致的机会会大大提升。

客户端如何扩展这六个字段

该表格即是 规范。各个客户端会对其中的部分内容进行宽松处理，并添加自己的字段。在你计划共享的前置信息编写之前，了解这一点很有价值。

Claude Code 是扩展最多的实现。它将 name 视为可选项，并默认使用文件夹名称。在个人或项目技能中，name 仅设置显示标签，而文件夹名称决定命令。它将 description 视为推荐而非必需，若未提供则回退到正文的第一段。在其技能列表中，它会将描述截断至 1,536 个字符。它会接受 license 和 compatibility 字段，但不会对它们进行任何处理。

在这六个字段之上，它又额外添加了大约十几个字段，包括 when_to_use、argument-hint、arguments、disable-model-invocation、user-invocable、disallowed-tools、model、effort、context、agent、hooks、paths 和 shell。

这里有个陷阱。这些扩展既不可移植，也不会被简单地忽略。

例如，Claude Code 支持诸如 argument-hint 和 when_to_use 之类的额外前置信息字段。带有这些字段的技能在 Claude Code 中可以完美运行。但如果你将同样的 SKILL.md 移动到更严格的验证路径，比如 Claude Desktop 或 Claude API，这些额外字段可能导致验证失败。

请看下面这个前置信息示例：

--- 
name: deck-builder 
description: Build presentation outlines. argument-hint: Give me a topic for the deck. 
---

Claude Code 可以接受 argument-hint 作为客户端特定的扩展。更严格的验证器可能会因 argument-hint 不属于规范中定义的六个字段而拒绝该文件。

这就是错误的表现形式：

Unexpected key(s) in SKILL.md frontmatter: argument-hint.
Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

实际规则很简单：如果某个技能只打算在单个客户端内使用，则使用客户端特定的扩展；否则，保持前置元数据仅限于规范定义的六个字段。这种区别很重要，因为可移植性不仅仅取决于另一个客户端是否能读取该文件，而在于是否能在没有客户端特定字段导致故障的情况下发现并验证相同的技能。

对于 deck builder，没有必要冒这个风险。它仅使用规范定义的六个字段，Claude Code 会直接加载而无需修改。这样可以使技能与格式的可移植子集保持一致，并且相同的 SKILL.md 在兼容的客户端之间移动会更容易。

常规文件夹

除了SKILL.md，规范定义了三种约定：

• scripts/：代理运行的代码。自包含，错误明确，不会挂起。我们的包含 validate_deck.py。

• references/：代理按需打开的文档。保持每个文件内容简洁。我们的包含 narrative-patterns.md。

• assets/：模板、模式和图像。deck-builder 不需要此目录。

不同的客户端可能会识别额外的目录。例如，Antigravity 还记录了 examples/ 和 resources/。但这些目录只是约定，而不是技能格式的固定要求。

实际上重要的是 SKILL.md 如何指向这些文件。代理会遵循你定义的相对路径，因此你可以根据技能的工作方式来组织支持材料。只要合适，就可以保留 scripts/、references/、assets/ 或客户端特定的目录，然后在 SKILL.md 中显式引用它们。

这些约定仍然具有人性化的重要好处。当有人打开他们未编写的技能时，熟悉的目录会立即告诉他们在哪里可以找到可执行代码、参考材料、示例或其他支持资源。

指向您自己的文件

始终使用相对于技能根目录的路径，永不使用绝对路径。

See [the narrative patterns guide](references/narrative-patterns.md) when the instructions are unclear.

Check the outline before writing slides:

    python3 scripts/validate_deck.py --file outline.md

保持引用只有一层深度。指向指向更多文件的文件会让代理在导航上消耗轮次，而不是去工作。而 /Users/you/dev/skills/... 在队友克隆仓库的瞬间就会失效。

客户特定的改进：

Claude Code 会将 ${CLAUDE_SKILL_DIR}（即存放 SKILL.md 的文件夹）替换到 allowed-tools 中的正文和 Bash 规则两处。在两处都使用它，可以让技能在不弹出权限提示的情况下运行其自身捆绑的脚本。这是 Claude Code 的扩展，因此在便携技能中请保持使用纯粹的相对路径。

在提交前进行验证

随标准一起提供的参考库会检查前置元数据和命名：

skills-ref validate ./deck-builder

在 CI 中运行验证器，以便在技能进入运行时之前捕获格式错误的技能。

前置元数据错误对机器来说易于检测，但在代理运行后却难以诊断。令人沮丧的是，客户端并不总是以相同方式暴露这些失败。严格的验证器可能会直接以明确的错误拒绝该技能，而另一个客户端可能根本不列出该技能，导致你没有明显的迹象表明问题出在前置元数据上。

十分钟内构建版本 1

首先，选择正确的文件夹

规范说明了技能 内部 应包含什么内容。它 不 说文件夹应放置的位置，且各客户端有所不同。若在此处出错，是导致首个技能永不触发的最常见原因，因此在运行 mkdir 之前请先确认。

客户端	项目范围	个人范围
Claude Code	.claude/skills/	~/.claude/skills/
VS Code / Copilot	.github/skills/, .claude/skills/, .agents/skills/	~/.copilot/skills/, ~/.claude/skills/, ~/.agents/skills/
Google Antigravity	.agents/skills/	~/.gemini/config/skills/

.agents/skills/ 是新兴的跨客户端约定。Claude Code 是个大例外：其文档命名为 .claude/skills/ 和 ~/.claude/skills/，并且根本不列出 .agents/skills/。

重叠部分是有用的部分。VS Code 也会扫描 .claude/skills/ 同样，因此一个文件夹能够满足这两个最典型的客户端。这就是本指南默认使用它的原因。

# Claude Code, and VS Code / Copilot, which both scan this location
SKILLS_DIR=.claude/skills

# Antigravity, or VS Code if you prefer the cross-client convention
# SKILLS_DIR=.agents/skills

mkdir -p "$SKILLS_DIR/deck-builder"

然后编写文件

创建 deck-builder/SKILL.md：

---
name: deck-builder
description: Helps make presentations.
---

# Deck Builder

Never start writing slides immediately. Decide what the deck is for first.

## Workflow

### Step 1: Brainstorm

Before any slide exists, write a `## Brainstorm` block answering three questions:

- **Audience.** Who is in the room, how long do you have, what do they
  already know, and what decision do they need to make?
- **Core message.** One sentence. If the audience remembers nothing else,
  what is it?
- **Arc.** How the deck moves from opening to ask.

If the request does not give you enough to answer these, ask the user
before continuing. Do not guess the audience.

### Step 2: Write slides

One idea per slide. Six bullets maximum. End on the ask, never on a
body slide.

这是一个完整可用的技能，单文件仅二十八行，无任何依赖。

它的以下三点适用于你将要构建的一切：

• 跳过背景说明： 不解释什么是幻灯片，代理已经知道。

• 规则可检验： “最多六个要点”可以通过目视确认。“遵循演示最佳实践”则不行。

• 描述故意写得不好： Helps make presentations. 正是那种模糊的概述，导致无法触发。修复它就是版本 2。

在 VS Code 或 Claude Code 中运行

文件已存在。现在确认你的客户端能看到它。

这比你想象的更重要。如果客户端永远发现不了某个技能，它就不会被加载到上下文中，表现出来的症状可能与描述薄弱或调校不当的技能完全一样。

在修改触发逻辑之前，先确认客户端确实能看到该技能。这个简单的检查能告诉你是在调试发现问题还是触发问题。

两个客户端均提供两种运行技能的方式，它们测试的内容不同：

• 按名称调用： 这会跳过描述，直接测试 主体。

• 提出应触发它的问题，不命名它。这会测试 描述。

两种路径都要测试。显式调用 能确认技能本身有效且其指令被遵循。自动触发 用来检验 description 是否足够具体，以便代理能够识别何时应用该技能。

这一区分让调试变得简单得多。如果显式调用成功但自动触发失败，说明技能主体正常工作，问题出在描述上。这就是进入 版本 2、调整触发逻辑的信号。

在 Claude Code 中

1. 重启 Claude Code 以便发现新文件夹。它会实时加载对已有 skills 文件夹的修改，但若该文件夹在会话开始时不存在，则需要重启。

2. 输入 /skills 并确认列出 deck-builder。

3. 直接用 /deck-builder 调用，或者即使你提到“创建演示文稿”，它也会自动检测到 /deck-builder 并根据技能指令开始执行工作流。

4. 在全新会话中测试触发。提出问题，但不要命名技能：

   你能为周四的董事会会议准备一些关于 Q3 迁移的材料吗？

命令名称来源于 文件夹 名称，而不是前置信息中的 name。重命名文件夹后，命令也会随之改变。Claude Code 还将自定义命令合并到了 skills 中，所以 .claude/commands/deploy.md 和 .claude/skills/deploy/SKILL.md 都会生成 /deploy。

在 VS Code 中

1. 打开已安装 GitHub Copilot 的项目。

2. 打开 Copilot Chat 面板。Agent Skills 快速入门建议在模式下拉菜单中选择 Agent 模式，这是因为代理可以在此模式下运行终端命令。VS Code 自身的技能文档未说明模式要求，因此如果在其他模式下看不到技能，请先切换到 Agent 模式，再假设文件有问题。

3. 输入 / 以列出可用的技能和提示。技能会以斜杠命令的形式出现在提示文件旁边。/skills 会打开 Configure Skills 菜单，您可以在此确认 deck-builder 已被识别。

4. 从 / 列表中选择它以运行。您可以追加上下文，例如 /deck-builder for the board meeting。

5. 再次提出同样的未指定目标问题。

因为 VS Code 也会扫描.claude/skills/，您可以在那里重复使用相同的 deck builder 目录，而无需更改其结构。当同一个技能需要在 Claude Code 和 VS Code 之间共享时，这提供了一个便捷的共享位置。

如果您更倾向于遵循 VS Code 自身的约定，请将技能放置在 .github/skills/ 而不是。重要的不是选择一个单一的通用文件夹，而是将技能放置在目标客户端实际查找的位置，并在调试技能本身之前验证其是否被发现。

成功是什么样子

没有该技能时，模型通常会从第一张幻灯片打开：

Slide 1: Q3 Migration Overview
Slide 2: Goals
Slide 3: Timeline
Slide 4: Challenges
Slide 5: Results
Slide 6: Thank You

没有该技能，代理可以生成看似完全合理的内容：一系列熟悉章节的幻灯片，但缺乏对该幻灯片实际服务对象或需要完成目标的明确决定。

加载该技能后，在写出第一张幻灯片之前，行为就会发生变化。代理会先创建一个 Brainstorm 块，覆盖受众、核心信息和叙事弧线。它甚至可能停下来提出澄清性问题，因为诸如 “为周四的董事会会议准备一些材料” 这样的请求仍然留下一个关键细节未得到解答：董事会需要决定什么？

这种停顿正是 Version 1 的真正价值所在。代理不会急于生成幻灯片，而是花一点时间建立应指导幻灯片制作的思路。

当它不起作用时

症状	可能原因	解决方案
技能在 /skills 中缺失	该文件夹位于客户端未扫描的位置，或者会话早于该文件夹的存在	重新检查路径表，然后重启
已列出，但未找到 /deck-builder	命令来源于文件夹名称	将文件夹重命名为 deck-builder
调用有效，但触发失败	描述过于狭窄。这是版本 1 的预期行为	继续使用版本 2
技能已加载，但代理仍然生成幻灯片	对指令的遵循程度因模型而异	在编辑技能之前先尝试其他模型
前置元数据被视为意外键而被拒绝	在更严格的路径上出现了客户端特定字段	仅限于规范规定的六个字段

第四行值得停下来思考。当输出令人失望时，本能是去修改技能。先更换模型。否则你会同时调试两个变量，而只有其中一个是你的文件。

版本 2：让其每次都被触发

一个永远不会被触发的技能毫无价值。description 承担了全部责任。这是代理在决策前看到的你的技能的唯一部分。

版本 1 的描述是 Helps make presentations. 它在出现 “presentation” 时触发，而在 “把东西准备好以便周四使用” 时保持沉默，而这正是人们实际提出的请求方式。

四项原则

• 以指令的形式编写：“在何时使用此技能……” 胜过 “此技能的作用……”。代理正在做出决策，因此应直接针对决策。

• 描述意图：代理匹配用户所请求的内容，而非你的架构。

• 强势一点： 列出适用的情形，包括用户回避你的词汇的情况。

• 注意上限： 1024 个字符是硬性上限，调优过程中描述会增长。

调整技能描述时，一个容易被忽略的细节是：并非每个请求都需要技能。当任务涉及多个步骤、领域特定判断，或难以自行可靠重复的流程时，代理倾向于使用技能。

比如 “幻灯片的合适字体大小是多少？” 通常不需要 deck builder。代理可以直接回答。当请求需要可重复的工作流时，描述才变得有价值，例如确定受众、定义核心信息、选择合适的叙事弧线，然后制作幻灯片。这正是一段多步骤工作，编写良好的技能在此能发挥作用。

测试触发而非猜测

你可以这样衡量。构建约 20 个带有标签的真实提示，以表明它们 应该 触发技能：8 到 10 个正例，8 到 10 个负例。将它们存储在 evals/trigger_queries.json 中。

[
  {
    "query": "can you put something together for thursday's board meeting on the q3 migration",
    "should_trigger": true
  },
  {
    "query": "I need to walk the new hires through how our deploy pipeline works, 20 mins",
    "should_trigger": true
  },
  {
    "query": "make the font bigger on slide 4 of this pptx",
    "should_trigger": false
  },
  {
    "query": "write me a one-page summary of the q3 migration for the wiki",
    "should_trigger": false
  }
]

有价值的正例是指技能有帮助，但措辞并未明说的情况。第一个例子从未提到“deck”、“slides”或“presentation”。如果提示已经明确要求技能所做的事情，任何描述都能通过，你也学不到任何东西。

最有价值的负面测试是近似失误：提示包含与技能相同的词汇，但实际上需要不同的任务。类似“Write a Fibonacci function”的提示几乎毫无用处，因为它与演示工作没有重叠。“Make the font bigger on slide 4”则更有用，因为它明确提到了幻灯片，但任务是编辑现有幻灯片而不是设计整套幻灯片。

维基摘要也是一个强烈的边界情况。它可能涉及相同的迁移，但用户要求的是书面文档，而不是演示。这些近似失误能告诉你描述是否理解了请求的意图，而不仅仅是匹配熟悉的词汇。

模型行为在每次运行之间会有差异，因此对每个查询运行三次并计算触发率。正例的触发率应高于0.5，负例应低于0.5。

不要过拟合

针对你编写的每个查询进行调优会产生一个在对应表述上有效但在真实用户面前失效的描述。

将数据集划分为大约60%的训练集和40%的验证集，并在每个集合中保持正负例的比例。利用训练集的失误来指导编辑。仅使用验证集来检查编辑是否具备泛化能力。

1. 在两个集合上进行评估。

2. 找出训练集的失误。遗漏触发意味着太窄；误触发意味着太宽。

3. 朝着失误所代表的一般类别进行修订。永远不要直接粘贴失败查询中的关键词，这属于过拟合。

4. 重复此过程，通常不超过五次。

5. 选择验证率最高的迭代。这通常不是最后一次迭代。

结果

# Version 1 — fires on the word "presentation" and little else
description: Helps make presentations.

# Version 2 — tuned against 20 labelled queries
description: >-
  Turn a request for a presentation into a slide outline. Brainstorm the
  audience, core message, and narrative arc first, then write slides. Use
  when someone asks for a deck, slides, a presentation, a readout, a board
  update, or a talk, including when they only say "put something together
  for Thursday" without naming a format. Not for editing existing slide
  files or for writing prose documents.

两项改动起到了作用。它通过命名‘头脑风暴-然后构建’流程，使其对所做之事的描述更具体；同时，通过涵盖从未提及‘幻灯片’的请求，使其适用范围更广。

这句话的结尾部分是大多数人会跳过的。通过说明技能不适用于什么，可以防止误触发的近失。

版本 3：编写能赢得其 token 的主体

技能激活后，其完整主体会与对话、系统上下文以及其他所有激活的技能争夺注意力。请将其视为一种预算。

从真实专业知识出发

技能编写中最常见的失败是让 LLM 在没有领域输入的情况下编写技能。返回的结果虽然流畅但毫无用处：'考虑你的受众','保持幻灯片清晰'。

有效的技能来源于已有的事物。拿起你团队实际称赞的牌组，写下它为什么有效。拿出有人评论说："这是三副牌组，而不是一副"的审阅意见。拿出因第二张幻灯片失去观众而被截断的汇报。

对于 deck-builder，原始材料是你已经对草稿给予人们的反馈。

删除代理已知的内容

对每一行自问：如果没有它，代理会弄错吗？如果不会，则删除。

## Slide design

A slide is a single screen in a presentation. Slides should be visually
clear and not too crowded. Audiences find it hard to read a lot of text
on a screen, so you should use bullet points to summarize your ideas.


## Slide design

One idea per slide. Six bullets maximum, each under 120 characters.
Anything longer belongs in speaker notes, not on the slide.

把它定义为一个连贯的工作

范围太窄会让一项任务牵涉四项技能；范围太宽则描述无法精准命中。

构思大纲和制作幻灯片是一项工作，因为后者依赖于前者。添加图表设计、演讲指导以及编辑现有 .pptx 文件相当于一人戴四顶帽子的四项工作。这就是我们经过调整的描述明确排除它们的原因。

将指令的力度与任务的脆弱程度相匹配

留出空间 以容纳多种可行的方法。解释为什么 胜过僵化的命令，因为理解目的的代理能够更好地适应。

## Choosing an arc

Pick the arc that matches what the audience needs to do:

- They must decide something: Situation, Complication, Resolution
- They are skeptical: lead with the objection, then dismantle it
- They need to learn: chronological, simplest case first
- They already agreed: skip persuasion, go straight to the plan

要明确规定顺序重要的地方：

## Order of operations

Do these in order. Do not write slides before the brainstorm exists.

1. Write the `## Brainstorm` block
2. Run `python3 scripts/validate_deck.py --file outline.md`
3. Write slides only after it exits 0

大多数技能都需要两者。按章节逐段校准。

提供默认选项

列出五个选项会引发深思：

You could use SCR, PAS, AIDA, the pyramid principle, the hero's journey...


Default to Situation, Complication, Resolution. It fits most internal
readouts. For a skeptical audience, lead with the objection instead.

完成大部分工作的四种模式

误报

在大多数技能中，这是最高价值的部分。这不是建议，而是对代理否则会犯的错误的纠正：

## False Positives

- "Put something together" is not a brief. It gives you no audience and
  no decision. Ask before you build; do not invent an audience.
- A deck for a 15-minute slot is not a shorter version of the 45-minute
  deck. Fewer slides with the same message, not the same slides compressed.
- If the core message needs an "and" to state it, it is two decks. Split
  it or pick one.
- Our leadership readouts open with the ask, not the background. Reverse
  the arc for anyone above director level.

那是模型无法猜到的那类东西——它是你的演示样式和设计约定，也是文件中最宝贵的一行。

将误报保留在 SKILL.md 中，而不是参考文件。代理需要在遇到情况之前就拥有它们(之前)，并且它不知道该打开一个描述它不存在的陷阱的文件。

每次你在任务进行中纠正代理时，这种纠正都应该放在这里。

模板

当输出形状很重要时，请展示形状。代理对结构的模式匹配远胜于他们对关于结构的散文的遵循。

## Outline format

Produce exactly this structure:

```markdown
# Deck: