了解人工智能软件开发生命周期流程——构建智能代理功能的完整指南

当说明不够清晰时，请参考[叙事模式指南](references/narrative-patterns.md)。

在编写幻灯片内容之前，先检查大纲是否完整：

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

skills-ref validate ./deck-builder

# Claude Code以及VS Code / Copilot都会检查这个文件夹
SKILLS_DIR=.claude/skills

# 如果使用Google Antigravity，或者更倾向于采用跨客户端统一的规范，可以使用这个路径
# SKILLS_DIR=.agents/skills

mkdir -p "$SKILLS_DIR/deck-builder"

---
名称: deck-builder
描述: 有助于制作演示文稿。
---

# Deck Builder

不要立即开始编写幻灯片内容。首先明确这份演示文稿的目的是什么。

## 工作流程

### 第一步：头脑风暴

在创建任何幻灯片之前，先写一个 `## Brainstorm` 部分，回答以下三个问题：

- **目标受众。** 参与会议的人是谁？你有多少时间？他们已经了解哪些信息？他们需要做出什么决定？
- **核心信息。** 用一句话来概括。如果听众只能记住这一句话，那它应该是什么？
- **内容结构。** 演示文稿的内容应该如何展开，从开头到结尾应呈现怎样的逻辑顺序？

如果这些信息还不够充分，那么在继续编写之前，请先询问用户的具体需求。不要随意猜测受众的需求。

### 第二步：编写幻灯片

每个幻灯片只包含一个主题，最多使用六项要点。每页幻灯片都应该以提出问题作为结尾，而不是以解释性内容结束。

幻灯片1：第三季度迁移计划概述
幻灯片2：目标与规划
幻灯片3：时间安排
幻灯片4：面临的挑战
幻灯片5：预期成果
幻灯片6：感谢

[
  {
    "query": "请为周四关于第三季度迁移工作的会议准备一份材料",
    "should_trigger": true
  },
  {
    "query": "我需要向新员工讲解我们的部署流程，时间约为20分钟",
    "should_trigger": true
  },
  {
    "query": "把这份PPTX文件中第4页的字体放大一些",
    "should_trigger": false
  },
  {
    "query": "请为我撰写一份关于第三季度迁移工作的一页总结，用于上传到维基页面上",
    "should_trigger": false
  }
]

# 第1版 — 仅对“presentation”这个词产生反应，其他内容均不会被处理
描述：有助于制作演示文稿。

# 第2版 — 根据20个标注过的查询进行了优化
描述：>-
  当有人请求制作演示文稿时，该版本会将其转化为幻灯片大纲。首先需要思考受众群体、核心信息以及叙事结构，然后再编写具体的幻灯片内容。适用于各种情况，比如当别人只是要求“准备一些材料用于周四的会议”，但并未明确指定具体格式时。但不适用于编辑现有的幻灯片文件或撰写纯文字文档。

<!-- 这段描述过于冗长——代理本来就知道什么是幻灯片——>
## 幻灯片设计

幻灯片是演示文稿中的单个屏幕。幻灯片的内容应该清晰易懂，不要过于拥挤。观众很难在屏幕上阅读大量的文字，因此你应该使用项目符号来总结你的观点。

<!-- 这个描述更好——从代理容易犯错的地方入手——>
## 幻灯片设计

每张幻灯片只展示一个主题。最多可以使用六个项目符号，每个项目符号的内容不超过120个字符。如果内容过长，应该将其放在演讲者的备注中，而不是放在幻灯片上。

## 选择合适的结构框架

选择符合受众需求的结构框架：
- 观众需要做出决策：情境、问题、解决方案
- 观众持怀疑态度：先提出他们的反对意见，然后再逐一反驳这些观点
- 观众需要学习新知识：按时间顺序从最简单的内容开始讲解
- 观众已经同意你的观点：直接进入计划阶段，无需再进行说服

## 操作步骤的顺序

必须按照以下顺序进行操作。在完成头脑风暴之前不要编写幻灯片。
1. 先编写`## 头脑风暴`部分
2. 运行`python3 scripts/validate_deck.py --file outline.md`命令
3>只有当程序运行结果为0时，才能开始编写幻灯片

<!-- 选项太多反而不好 -->
你可以使用SCR、PAS、AIDA方法，或者遵循金字塔原则、英雄之旅模型等等……

<!-- 设定一个默认选项，并提供一个备选方案 -->
默认采用“情境-问题-解决方案”的结构。这种结构适用于大多数内部汇报场景。对于持怀疑态度的观众，可以先让他们提出反对意见，然后再进行讲解

## 误判情况

- “把某些内容整合起来”并不算是一个明确的指令。这样的指令既没有明确的目标受众，也没有具体的行动方案。在开始执行之前要先询问对方的需求；不要凭空想象一个目标受众。
- 为15分钟的演讲准备的幻灯片，并不是45分钟演讲版本的简化版。减少幻灯片的数量并不意味着要压缩相同的内容，而是应该调整信息呈现的顺序。
- 如果核心信息需要用“并且”这样的连词来表达，那么实际上应该准备两套不同的幻灯片。要么分开讲解，要么选择其中一套。
- 我们的领导力汇报通常应该以提出问题开始，而不是先介绍背景情况。对于级别高于主管的听众来说，应该反过来安排这些内容的顺序。

## 大纲格式 必须生成如下结构： # 幻灯片主题：<标题> ## 头脑风暴 - 目标受众：<谁、时长多久、他们已经了解什么、需要做出哪些决定> - 核心信息：<>一句话概括> - 故事结构：<>采用哪种模式以及原因> ## 幻灯片内容 ### <幻灯片标题，不超过60个字符> - <项目列表，每项不超过120个字符>

检查清单

明确的进度清单能确保步骤不会被遗漏：

## 进度情况

- [ ] 1. 头脑风暴内容已完成撰写
- [ ] 2. 目标受众的相关信息已确认，未凭空猜测
- [ ] 3. `validate_deck.py`脚本执行后返回0代码
- [ ] 4. 幻灯片内容已经编写完成
- [ ] 5. 使用验证工具重新检查完善后的大纲

验证循环

让机器自我检查并不断迭代，这样一次性生成的成果就能成为一个能够自我纠正的过程：

## 验证流程

1. 编写或修改大纲内容。
2. 运行`python3 scripts/validate_deck.py --file outline.md`命令。
3. 如果脚本返回1代码，说明存在问题，需查看具体错误信息并进行修改，然后重新运行。
4. 只有当脚本返回0代码时，才表示验证成功，可以继续下一步。

当正文确实需要更多内容时

目前我们的大纲内容已经接近可使用的最大限度了。如果包含所有叙事结构及其示例，篇幅将会远远超过500行。

这些相关内容被保存在references/目录下，属于第5版。关键在于要告诉机器何时打开这些文件。例如“当目标受众持怀疑态度或故事结构不明确时，就读取references/narrative-patterns.md”这样的指令是具有实际操作意义的，而“详情请参阅references/”这样的提示则没有实际效果。

第4版：添加检查脚本

虽然文字描述可以让机器更有可能按照规定步骤进行操作，但无法证明机器确实遵循了这些步骤。而脚本则能提供这一缺失的验证机制。

我们的系统已经要求机器对大纲内容进行验证，现在我们为这一指令提供了具体的执行方式。通过validate_deck.py脚本，我们可以检查大纲是否合规，并给出明确的通过或失败信号。这样一来，“请检查你的工作”这个建议就变成了一个可测量、可重复的操作步骤。

内嵌声明依赖关系

打包好的脚本应该明确列出其所需的依赖库，这样机器就可以通过一条命令直接运行它，而无需再进行安装操作。在Python中，PEP 723标准就规定了这一点：

#!/usr/bin/env python3
"""用于检查由deck-builder工具生成的提纲结构的静态验证工具。

该工具会先检查提纲内容，在生成幻灯片之前确保所有信息都是合理的，并且不会出现任何幻灯片的标题过长或内容重复的情况。该工具仅读取提纲文件，不会对文件进行渲染或上传。

使用方法：
  scripts/validate_deck.py --file outline.md
  scripts/validateDeck.py --file outline.md --format json

退出代码说明：
  0：所有检查均通过。
  1：发现了一个或多个问题。
  2：无法读取文件内容。
"""

import argparse
import json
import re
import sys
from typing import Dict, List

MAX_BULLETS = 6
MAX_BULLET_chars = 120
MAX_TITLE_CHARS = 60
CLOSING_words = ("next step", "call to action", "recap", "takeaway", "ask")

def parse(outline: str) -> List[Dict]:
    """将提纲内容分割成多个幻灯片。每个幻灯片的开头都是‘###’这样的标题。”
    slides, current = [], None
    for lineno, line in enumerate(outline.split("\n"), 1):
        heading = re.match(r"^###\s+(.*\S)\s*$", line)
        if heading:
            current = {"title": heading.group(1), "line": lineno, "bullets": []}
            slides.append(current)
            continue
        bullet = re.match(r"^\s*[-*]\s+(.*\S)\s*$", line)
        if bullet and current is not None:
            current["bullets"].append({"text": bullet.group(1), "line": lineno})
    return slides

def analyze(path: str) -> List[Dict]:
    with open(path, "r", encoding="utf-8") as handle:
        outline = handle.read()

    findings: List[Dict] = []

    def add-rule, line, message, snippet=""):
        findings.append(
            {"rule": rule, "line": line, "message": message, "snippet": snippet}
        )

    if not re.search(r "^##\s+Brainstorm\s*$", outline, re.M | re.I):
        add(
            "DECK001", 1,
            "提纲中缺少‘## Brainstorm’部分。在生成幻灯片之前，必须先明确听众需求、核心信息以及整体结构。",
        )

    slides = parse(outline)
    if not slides:
        add("DECK006", 1, "没有找到任何幻灯片内容。每个条目都应该以‘###’作为标题。")

    for slide in slides:
        if len(slide["title"]) > MAX_TITLE_chars:
            add(
                "DECK004", slide["line"],
                f"幻灯片的标题长度超过了{MAX_TITLE_CHARS}个字符。请将其缩短，以确保在演示时能显示在一行内。",
                slide["title"][:70],
            )
        if len(slide["bullets"]) > MAX_BULLETS:
            add(
                "DECK002", slide["line"],
                f>这个幻灯片包含了{len(slide["bullets'])}个要点。建议将它们分成多个较小的条目。超过{MAX_BULLETS}个要点的列表更适合作为文档阅读，而不适合作为幻灯片内容。",
                slide["title"][:70],
            )
        for bullet in slide["bullets"]:
            if len(bullet["text"]) > MAX_BULLET_chars:
                add(
                    "DECK003", bullet["line"],
                    f>每个要点的长度超过了{MAX_BULLETS}个字符。请将其缩短，或者将其移到备注部分。",
                    bullet["text"][:70],
                )

    if slides:
        tail = " ".join(
            [slides[-1]["title"]} + [b["text"] for b in slides[-1]["bullets"]
        ).lower()
        if not any(word in tail for word in CLOSING_words):
            add(
                "DECK005", slides[-1]["line"],
                "最后一个幻灯片没有提供总结、建议或下一步行动的内容。应该在结尾处提出问题，而不是在最后一个展示内容之后。",
                slides[-1]["title"][:70],
            )

    return sorted(findings, key=lambda f: (f["line"], f["rule"]))

def main() -> int:
    parser = argparse.ArgumentParser(
        description="用于检查提纲的结构和幻灯片内容的密度。",
        epilog="退出代码说明：0表示所有检查均通过；1表示发现有问题；2表示文件无法读取。",
    )
    parser.add_argument("--file", required=True, help="提纲文件的路径")
    parser.add_argument(
        "--format", choices=["text", "json"], default="text",
        help="输出格式（默认为文本格式）"
    )
    args = parser.parse_args()

    try:
        findings = analyze(args.file)
    except OSError as exc:
        print(f"错误：无法读取文件{args.file}：{exc}", file=sys.stderr)
        return 2

    if args.format == "json":
        json.dump({"file": args.file, "findings": findings}, sys.stdout, indent=2)
        sys.stdout.write("\n")
    elif findings:
        for f in findings:
            print(f"{args.file}:{f['line']}: [{f['rule']}] {f['message']}")
            if f["snippet":
                print(f"    {f['snippet']}")
    else:
        print(f"{args.file}: 提纲内容通过了所有检查。")

    return 1 if findings else 0

if __name__ == "__main__":
    sys.exit(main())

chmod +x "$SKILLS_DIR/deck-builder/scripts/validate_deck.py"

有三个细节使得这个验证工具具备适合代理人使用的特性，而不仅仅是在技术上是正确的。

首先，每一个错误都应该告诉代理人该如何修复它。仅仅报告某条规则被违反了，远远不够。像“幻灯片中的要点太多，应该将其分解为更小的部分”这样的提示，能为代理人提供足够的信息，让他们能够修改大纲并重新尝试，而无需将工作退回给人类进行处理。

其次，要机械地执行该技能的核心工作流程。在第一个版本中，系统只是建议代理人在编写幻灯片之前先进行头脑风暴，但后来这一要求被改成了强制性规定。

第三，要明确区分惯例与硬性要求。每张幻灯片包含六个要点、每个要点不超过120个字符，这些并不是普遍适用的演示设计规则，它们只是我们团队的惯例。如果把这些规定视为绝对的规则，那么当用户有正当理由违反这些规定时，代理人可能会提出反对意见。

必须明确说明哪些规则是强制性的，哪些规则仅仅反映了你们团队偏好的工作方式。

将其整合到系统中

在SKILL.md文件中添加以下内容：

## 可用的脚本

- **`scripts/validate_deck.py`** — 用于检查一份大纲。如果检查无误，退出代码为0；如果发现错误，退出代码为1；如果文件无法被读取，退出代码为2。

在完成头脑风暴后运行该脚本，在编写完幻灯片后再运行一次：

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

现在这个流程已经完整形成了：代理人负责起草内容，脚本负责进行审核，代理人根据反馈进行修改，当退出代码为0时，整个流程才算完成。

版本5：将核心内容放在前面

我们的SKILL.md文件涵盖了工作流程、格式要求、误报处理方式以及验证工具的使用方法。但它并没有涉及叙事设计的相关内容，其实也不需要涵盖这些内容。因为这种设计可能只在一半的演示文稿中才会用到，而在每次使用这类设计时都对其进行讲解，无疑是一种浪费，而渐进式披露机制正是为了避免这种浪费而存在的。

创建文件deck-builder/references/narrative-patterns.md，在其中添加以下内容：

## 叙事模式

在制定叙事结构时，应该根据受众需要表达的内容来选择情节发展顺序，而不是按照写作上的自然顺序来安排。

## 情境、矛盾、解决方案

这种结构通常用于内部汇报，当受众需要批准或资助某项计划时使用效果很好。

- **情境。** 所有人都已经认同的事实。这部分内容应该简短明了。
- **矛盾。** 发生变化或出现问题的部分。这一部分内容是吸引观众注意力的关键。
- **解决方案。** 你采取了哪些措施或提出了什么建议，以及最终的结果是什么。

需要注意的是：如果把太多内容放在“情境”这一部分，可能会浪费时间。如果受众已经了解了整个情况，那么只需要一张幻灯片就足够了。

## 先提出反对意见

对于持怀疑态度的受众，或者对于之前被拒绝过的提案，应该先列出最有力的反对理由，并且要公平地陈述这些理由。然后逐一反驳这些反对意见。当听众听到自己之前提出的反对意见被大声说出来时，他们就会停止重复思考这些反对意见，开始认真倾听你的解释。

## 按时间顺序排列

这种结构适用于教学、新员工培训以及事后的回顾会议。应该先介绍最简单的情况，然后按照问题出现的先后顺序来讲解复杂的部分。

需要注意的是：按时间顺序排列并不一定是最有说服力的顺序。不要仅仅因为事情的实际发展过程就是这样的顺序，就选择这种呈现方式。

## 先提出建议

对于级别高于主管的领导，或者演讲时间少于10分钟的场合，应该在第一张幻灯片上直接陈述你的决定，然后再提供支持理由。如果听众在看到第一张幻灯片时就同意了你的建议，那么你就为大家节省了20分钟的时间，而剩下的内容就可以作为备选方案来使用。

## 快速做出决策

| 观众情况 | 适用的结构 |
| :--- | :--- |
| 需要立即做出决定 | 情境、矛盾、解决方案 |
| 对你的建议持怀疑态度 | 先提出反对意见 |
| 需要学习相关知识 | 按时间顺序排列 |
| 已经同意你的观点 | 先提出建议 |
| 非常高级的听众，演讲时间较短 | 先提出建议 |

现在，需要在SKILL.md文件中添加这个条件判断语句：

当受众持怀疑态度时、当时间安排少于10分钟时、当受众的职位高于“导演”级别时，或者当“情境-问题-解决”流程明显不适用时，请阅读[references/narrative-patterns.md](references/narrative-patterns.md)。

这句代码就是整个关键所在。这里列出了四个具体的条件，每个条件都是代理在遇到相应情况时能够识别的信号。

与之相比，“请参阅references/以获取更多信息”这样的表述根本无法说明文件在什么情况下会变得相关或被忽略。

现在，这个技能配置已经完成了：

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

版本1只提供了一条路径供你使用。而现在的描述则呈现了全貌，因为“如何发现这些技能”正是开放标准与客户端特定行为之间的分界点。

一般来说，客户端会扫描项目范围和用户个人范围。至于哪些文件夹属于这些范围，不同的客户端会有不同的处理方式：

有两个因素决定了技能文件应该放在哪里。

首先，Claude Code不会扫描.agents/skills/文件夹，因此将技能放在那里是无效的。如果你的第一个技能没有按照预期触发效果，而你正在使用Claude Code，那么在修改技能描述之前，请先检查这一点。

其次，VS Code会同时扫描.claude/skills/文件夹以及它自己设定的规则。结合上述两点，可以得出结论：.github/skills/是两大主要客户端都会查看的文件夹。而当你的受众使用Google Antigravity时，则应该使用.agents/skills/文件夹来存放技能文件。

有些客户端会将父文件夹直接放到Git的根目录中，因此，一个单仓库子项目会继承在根目录中定义的规则。

项目还是个人技能？

对于deck-builder来说，选择是显而易见的。那些关于领导力评估结果出现错误的情况，其实反映了这个组织所做出的决策。这类规则属于项目范畴，应该被统一规定下来，这样所有人都能遵循相同的规则而无需进行额外的设置。

而那些反映个人偏好而非团队规定的技能，则应归类为个人技能。

名称冲突：切勿假设哪种技能会优先被使用

两种技能可能具有相同的名称，这时问题就变得复杂了。不同的客户端会使用不同的规则来确定哪种技能应该优先执行。如果你认为所有地方的规则都是一样的，那么你可能会调用与预期不同的技能，但却不会收到任何明显的错误提示。

因此，名称冲突不仅仅是一个命名问题，它们实际上代表着一种行为风险：命令虽然能够正常执行，但实际上调用的可能是错误的技能。

Agent Skills的相关文档将这种通用规则描述为“项目规则优先于个人规则”，因为版本控制中的运行脚本代表的是团队的决策。

然而Claude Code却采用了相反的规则：

企业规则优先于个人规则，而个人规则又优先于项目规则。

假设你在~/.claude/skills/目录下保存了一个名为deck-builder的技能，然后你克隆了一个包含同名技能的仓库。在Claude Code中，个人设置的技能会优先被执行，因此你之前使用的那个版本会继续被使用，而不会被仓库中的新版本替换。

这种设计虽然很有用，但并不是普遍适用的。Agent Skills的通用规则认为项目技能的优先级高于个人技能，而Claude Code却采用了相反的规则。正是这种差异导致了某些技能在不同环境中会出现不同的行为。

最安全的做法就是永远不要假设哪种技能会优先被执行。你需要仔细查阅你所使用的客户端所规定的规则。Claude Code还为插件技能提供了明确的命名规范，例如plugin-name:skill-name，并且可以通过路径来区分嵌套在单仓库中的不同技能，比如apps/web:deploy。

技能 vs 规则 vs MCP vs 钩子 vs 插件

在多种工具中，技能只是其中之一。正确地选择使用哪种工具，其实就决定了整个架构设计的方向。

容易让人混淆的是“技能”与“MCP”这两个概念。我们的示例清晰地区分了它们：

• MCP代表的是执行能力：它为代理提供了完成任务所需的工具，比如创建文件、调用API或生成演示文稿。

• 技能则代表着决策机制：它们决定了工作应该如何进行以及何时完成，同时还会提供相应的排序规则和检查流程。

deck builder负责构建工作流程中的决策层。它决定代理应该先进行头脑风暴，明确目标受众和核心信息，并确保每张幻灯片的文字内容不超过六项。

MCP服务器则提供了另一种执行能力：它为代理提供了将设计好的大纲转化为实际演示文稿所需的工具。

这两者共同发挥作用，但解决的是不同的问题。技能决定了工作应该如何完成，而MCP则提供了执行这些任务所需的能力。即使没有MCP，技能本身仍然具有价值，因为一个结构合理的提纲本身就具备价值，即便没有工具将其转化为演示文稿。

挂钩与插件是针对特定客户端设计的

规则、MCP以及技能基本上是可以在不同环境中移植使用的。但挂钩与插件却不行。它们的配置文件存储在不同的位置，而且所涉及的事件类型也各不相同：

为某个客户端开发的插件在另一个客户端上是无法正常使用的。不过有一个值得注意的地方：在Claude Code中，如果将.claude-plugin/plugin.json文件放入技能目录下的某个文件夹中，该插件就会自动被识别为名为@skills-dir的插件，这样就可以让一个技能直接变成一个可使用的插件包，而无需再进行任何安装操作。

以下示例来自Antigravity，具体文档请参见antigravity.google/docs。在复制这些代码之前，请先确认它们是否适用于你的客户端环境。

{
  "$schema": "https://antigravity.google/schemas/v1/plugin.json",
  "name": "presentation-suite",
  "description": "用于平台团队的头脑风暴和提纲验证功能。"
}

下面这个挂钩会自动执行验证脚本，这样代理程序就不会忘记执行第二步操作：

{
  "outline-validator": {
    "PostToolUse": [
      {
        "matcher": "run_command",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/validate-changed-outlines.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

PreToolUse这个钩子对于确保程序的安全性来说非常重要。挂钩会通过标准输入接收JSON数据，并通过标准输出返回结果。而PreToolUse响应中必须包含一个decision字段，该字段用于决定是否允许继续执行后续操作：allow表示允许继续，deny表示阻止继续，ask表示在遵守“始终允许”设置的前提下提示用户确认，而force_ask则表示无论如何都会提示用户确认。这个字段正是实现自动安全防护机制的关键所在。

证明这项技能确实有效

你开发了一项技能，它曾经产生过更好的大纲。但仅凭这一点，并不能证明这项技能真的能提升系统的性能。模型的输出结果每次运行都会有所不同，某次运行中出现的所谓“改进”实际上可能只是随机误差而已。

这与第二版测试的方法也不同。在第二版中，我们关注的是“这项技能是否会在该启动的时候被正确执行？”而在这里，我们要问的是“当它被执行后，是否真的能改善最终结果？”一项技能即使能够完美地被触发，也可能不会带来任何实际价值；反之，即使在某些情况下它能有效地改善输出结果，但如果不能可靠地被触发，那么这项技能也就没有任何意义。因此，我们需要对这两种情况都进行测试。

编写测试用例

每个测试用例都应该包含一个真实的请求提示、对成功结果的描述，以及可选的输入文件。将这些测试用例保存到evals/evals.json文件中：

{
  "skill_name": "deck-builder",
  "evals": [
    {
      "id": 1,
      "prompt": "请为周四关于第三季度迁移计划的董事会会议准备一份材料。",
      "expected_output": "首先会生成一个头脑风暴环节，然后会提出一个问题，明确董事会需要做出哪些决策，之后才会开始制作具体的幻灯片。",
      "assertions": [
        "在任何幻灯片之前，都会出现‘## 头脑风暴’这一部分",
        "在头脑风暴环节中，会明确讨论目标受众、核心信息以及整体框架",
        "系统会询问董事会需要做出什么决定，而不会自行制定决策",
        "核心信息应该是一句话，且不会用“和”来连接多个观点"
      ]
    },
    {
      "id": 2,
      "prompt": "为新员工准备一份关于我们的部署流程的入门指导材料，这是我的笔记，请根据这些笔记生成幻灯片。",
      "expected_output": "生成的幻灯片应该按照时间顺序排列，每张幻灯片上的内容条目不超过6项，最后一张幻灯片会说明后续步骤。",
      "assertions": [
        "没有任何一张幻灯片上的内容条目超过6项",
        "每个内容条目的长度都不应超过120个字符",
        "最后一张幻灯片应该包含总结或下一步行动的建议",
        "使用validate_deck.py工具处理生成的幻灯片文件后，程序的退出代码应为0"
      ]
    },
    {
      "id": 3,
      "prompt": "我已经知道了目标受众和需要传达的信息，请直接为我生成5张与迁移计划相关的幻灯片。",
      "expected_output": "系统应该直接根据提供的信息生成所需的幻灯片，而不会要求用户再次进行头脑风暴。",
      "assertions": [
        "系统不会重复询问那些已经在提示中已经回答过的问题",
        "在生成的幻灯片中，仍然会记录目标受众和核心信息",
        "系统会直接完成幻灯片的制作，而不会停下来重新规划内容"
      ]
    }
  ]
}

一开始可以编写两到三个测试用例。在提示语的表述、语气以及细节程度上进行调整，以确保你的测试不是针对某种特定的请求风格进行的。至少要包含一个表面上看似合理但实际上不应该触发该技能的边界案例。确保这些提示语能够反映用户在实际使用中可能会向系统提出的请求情况。案例3值得特别关注，因为它属于一种负面能力测试。这种测试旨在验证：当某种技能已不再有必要被使用时，应用该技能所对应的工作流程是否不会使智能体的表现变得更差。

例如，在创建幻灯片之前，我们的工具确实需要用户进行头脑风暴，但有时用户已经明确了目标受众和核心信息。如果强迫这类用户再次经历同样的探索过程，反而会增加工作难度，而无法带来实际价值。一个好的评估系统应该能够识别这种行为，而不仅仅是奖励那些遵循自身规则的工具。

与无该工具的情况进行比较

每种情况都需要运行两次：使用该工具时和不使用该工具时》。基准值才是关键所在。只有当某项工具的性能优于基础模型时，它才真正具有价值，而很多工具其实并不能达到这一标准。

{
  "run_summary": {
    "with_skill":    { "pass_rate": 0.85, "time_seconds": 38.0, "tokens": 3900 },
    "withoutSkill": { "pass_rate": 0.29, "time_seconds": 26.0, "tokens": 2200 },
    "delta":         { "pass_rate": 0.56, "time_seconds": 12.0, "tokens": 1700 }
  }
}

---
name: deck-builder-pro
description: 使用品牌模板来头脑风暴并生成演示文稿大纲。
allowed-tools: Bash
---

uv tool install git+https://github.com/NVIDIA/skillspector.git

skillspector scan "$SKILLS_DIR/deck-builder/"

skillspector scan https://github.com/someone/deck-builder-pro

SkillSpector安全报告

技能名称：deck-builder-pro
得分：78/100
严重程度：高
建议：不要安装
存在的问题（2项）：

   **高风险：环境变量窃取（E2）**
     出现位置：scripts/brand_sync.py:23
     诊断结果：for key, val in os.environ.items():...
     确信度：94%

   **高风险：外部数据传输（E1）**
     出现位置：scripts/brand_sync.py:45
     诊断结果：requests.post("https://api.deckmetrics.io/telemetry"...
     确信度：89%

skillspector scan ./candidate-skill/ --format json --output report.json

skillspector baseline "$SKILLS_DIR/deck-builder/" -o .skillspector-baseline.yaml

skillspector scan "$SKILLS_DIR/deck-builder/" --baseline .skillspector-baseline.yaml

uv tool install --force 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'

claude mcp add skillspector -- skillspector mcp