skill-conductor

Skill Conductor

全面管理 Agent 技能的生命周期：起草 → 测试 → 审查 → 改进 → 重复。

一个技能，统管一切——从架构到打包。核心循环始终相同：编写内容、测试、查看失败之处、修复、再次测试。

运行时要求（预检）

在任何会操作脚本的模式（CREATE、IMPROVE、VALIDATE、OPTIMIZE、PACKAGE）下，先运行预检代码块 → references/runtime-setup.md（检查 uv，设置 UV_BIN/SKILL_CONDUCTOR_DIR，验证 LLM 访问权限）。如果未安装 uv，请停止并告知用户。

沟通方式

留意上下文线索。如果用户是正在迭代自己作品的技能作者，请直接、专业地沟通。如果用户刚接触技能，请解释每个步骤背后的_原因_——不仅要说明该做什么，还要说明为什么重要。默认采用对话式表达，而不是机械的语气。

• 在确实存在选择时，解释其中的权衡
• 用具体示例代替抽象规则
• 出现问题时，解释根本原因，而不只是提供修复方法
• 指令使用祈使语气：“提取数据”，而不是“你应该提取数据”

模式

根据上下文判断模式。如果不明确，请询问。

模式	使用场景	处理内容
1. CREATE	“构建一个技能”、“为……创建新技能”	完整生命周期：意图 → 架构 → 脚手架 → 编写 → 测试
2. IMPROVE	“修复这个技能”、“它无法触发”	诊断 → 评估循环 → 门控式自我更新 → 迭代
3. VALIDATE	“测试这个技能”、“运行评估”	结构检查 + 触发测试 + BinEval 评分
4. REVIEW	“审查这个技能”、第三方评估	11 项质量门槛，快速且聚焦
5. OPTIMIZE	“改进触发效果”、“优化描述”	使用训练/测试集划分自动优化描述
6. PACKAGE	“打包以供分发”	验证 + 打包为 .skill 文件

---

模式 1：CREATE

第 1 步：明确意图

编写任何内容之前，提炼 2–3 个具体场景。

询问：

• “这个技能应该处理什么具体任务？”
• “用户会说什么来触发它？”
• “哪些情况不应该触发它？”

在清楚了解技能的功能、面向对象和适用时机之前，不要继续。这能避免最常见的问题：技能_能做一些事_，却在错误的情况下触发。

第 2 步：基线（TDD RED）

编写技能之前，先验证没有技能时 Agent 会失败：

1. 从第 1 步中选择一个场景
2. 在不启用该技能的干净会话中运行场景
3. 记录出错之处——Agent 猜了什么、遗漏了什么

如果 Agent 已经能完美处理，这个技能就没有必要。听起来显而易见，但这是最常被跳过、也最有价值的一步。

第 3 步：架构

从 references/patterns.md 中选择一种主要模式（可组合使用）：

模式	适用场景
顺序工作流	流程清晰，按步骤进行
迭代优化	通过多轮迭代改进输出
上下文感知选择	目标相同，但根据上下文使用不同工具
领域智能	需要工具访问之外的专业知识
多 MCP 协调	工作流跨越多个服务

选择自由度——这决定了技能赋予 Agent 的控制力与灵活性：

自由度	适用场景	示例
低（脚本）	易出问题、容易出错，必须精确执行	PDF 旋转、API 调用
中（伪代码）	有首选模式，但允许一定变化	数据处理
高（文本）	存在多种有效方法，需要判断	设计决策

**自由度测试：**问“如果 Agent 在此处出错，会有什么后果？”后果严重 → 自由度低（必须原样执行、不得修改的精确脚本）。后果轻微 → 自由度高（用文字描述，让它自行判断）。按步骤调整，而不是按技能调整——一个技能可以兼有不同自由度。

黄金法则：编写或审查任何技能之前，都要先阅读 references/sop-practices.md。其中包含规范的 10 条编写原则（通用）：预检、描述中不写流程、MOC（SKILL.md 是地图，不是正文）、新手作者、TWI“原因”、盲 Agent 测试、内联清单、一个概念只用一个术语、删繁就简（从 SKILL.md 中移除环境变量和密钥）、形式匹配故障。对于程序性技能（包含分支的业务流程：请求、报价、入职、升级），同一文件还包含深入的 SOP 方法论——格式选择、7 步流程、程序性清单。

第 4 步：搭建框架

uv run scripts/init_skill.py <skill-name> --path <output-dir> [--resources scripts,references,assets]

或手动创建：

skill-name/
├── SKILL.md          # required — the brain
├── scripts/          # deterministic operations (executed, not loaded)
├── references/       # detailed docs (loaded on demand)
└── assets/           # templates, images for output (never loaded)

第 5 步：编写 SKILL.md

Frontmatter

---
name: kebab-case-name
description: >
  [What it does]. Use when [4-5 phrasing variations users actually say] — even
  if they don't explicitly say "[canonical term]". Do NOT use for [negatives].
---

描述是最重要的一行——它决定技能是否会被触发。完整公式、强调条款以及 GOOD/BAD 示例见 references/sop-practices.md 原则 #2。编写前请先阅读。

• name：仅使用小写字母、数字和连字符。不得连续使用连字符。须与文件夹名称一致。最多 64 个字符
• description：最多 1024 个字符。不得包含尖括号。不得包含流程/工作流步骤
• 不要在描述中写工作流——测试表明：当描述列出流程步骤时，Agent 会遵循这些步骤并完全跳过正文

正文结构

# Skill Name

## Overview

What this enables. 1-2 sentences. Core principle.

## [Main sections]

Step-by-step with numbered sequences.
Concrete templates over prose.
Imperative voice throughout.

## Common Mistakes

What goes wrong + how to fix.

## Troubleshooting (if applicable)

Error: [message] → Cause: [why] → Fix: [how]

编写规则

• **一个概念只用一个术语。**选定“模板”后就始终使用它，不要混用 template/boilerplate/scaffold（原则 8）
• **SKILL.md 是地图，不是正文。**正文应是指向参考文档的目录；详细内容放在那里（原则 3）
• **SKILL.md 中不得包含机密信息/环境变量。**不得包含密钥、密码、令牌、环境变量值或用户绝对路径（/home/<user>、/Users/<user>）——引用它们即可，切勿直接写入（原则 9a）
• **渐进式披露。**SKILL.md 是核心（少于 500 行）。参考文档用于存放详细信息。深入一层即可
• **Token 预算。**频繁加载的内容：少于 200 个词。标准内容：少于 500 行。内容较多时：移至 references/
• **不要添加无关文件。**技能目录中不要放 README、CHANGELOG
• **脚本：**在同一段代码需要反复重写，或操作容易出错时，将脚本打包。失败时必须返回描述性 stdout/stderr
• **使用祈使语气。**写“提取数据”，不要写“你应该提取”，也不要使用大写的“MUST/NEVER”——解释优于规则（参见 references/sop-practices.md 原则 5，TWI）

步骤 6：测试用例与评测循环

这是关键步骤——大多数问题都隐藏在这里。将其视为三个子阶段。

在完整循环开始前，先对刚写好的内容进行微测试（在全新上下文中至少测试 5 次，并始终设置一个无指导对照组）→ references/pressure-testing.md。对于规范类技能——让 Agent 遵守其可能想要违反的规则的技能——必须使用该文件中的压力场景，不能省略。

6a. 运行前检查（启动任何任务前）

• evals/evals.json 已创建，包含 3–5 个提示词（参见 references/schemas.md）
• 已创建工作区目录：<skill-name>-workspace/iteration-1/
• 每个评测都有描述性名称（不能只是 eval-0）和 eval_metadata.json
• 已为执行器子 Agent 设置 Anthropic 密钥
• 从当前工作目录可以访问 uv 和 eval-viewer/generate_review.py

如果有任何一项不符合要求——先修复再继续。运行过程中缺少工作区目录会导致输出丢失。

6b. 运行循环（在同一轮中全部完成）

内容	关键操作	原因
启动启用技能的运行	每个评测启动一个子 Agent，启用技能，并将输出保存到 iteration-N/<eval-name>/with_skill/	并行运行 = 与单次运行耗时相同
在同一轮中启动基线运行	使用相同的提示词，不启用技能（或 IMPROVE 模式下使用旧版本快照），并将输出保存到 without_skill/ 或 old_skill/	如果等一会儿再运行，基线会随时间变化，无法比较
运行期间起草断言	从评测提示词中提取可验证的陈述	不要浪费子 Agent 运行所需的 5–15 分钟
收到每条通知时记录用时	立即将 total_tokens、duration_ms 保存到 timing.json	通知是唯一的数据来源——每条通知到达时立即处理，不要批量处理

6c. 运行后检查清单

• 已写入所有 timing.json 文件（每次运行一个）
• 每次运行都有一个 grading.json，包含字段 text、passed、evidence（而不是 name/met）
• 已汇总 benchmark.json：uv run scripts/aggregate_benchmark.py <workspace>/iteration-N --skill-name <name>
• 已完成分析检查——查看 agents/analyzer.md，了解需要关注的内容（区分度不足的断言、方差较大的评测、时间/令牌权衡）
• 已启动评测查看器：uv run eval-viewer/generate_review.py <workspace> --skill-name <name> --benchmark <path>
  • 在无头模式下：使用 --static <output.html>，并将文件发送给用户
  • 对于第 2 次及之后的迭代：添加 --previous-workspace <previous-iteration-path>
• 我开始编辑技能之前，用户已经查看了查看器

最后一条是陷阱。如果跳过用户审核，仅根据自己对输出的解读来“改进”，你优化的就会是自己的偏好，而不是用户的需求。

步骤 7：验证与重构

1. 对于正确的查询，技能是否会自动触发？
2. Agent 是否遵循正文中的指令（而不只是描述）？
3. 输出是否满足用例要求？
4. 是否不会对无关查询触发？

如果有任何一项不符合——继续迭代。找出 Agent 如何为绕过技能寻找理由，堵住漏洞，然后重新验证。

---

模式 2：改进

步骤 1：诊断

完整阅读现有的 SKILL.md。识别问题类别：

问题	表现	修复方法
触发不足	技能未加载	在描述中添加关键词、触发短语和文件类型
触发过度	对无关查询也会加载	添加负向触发条件，使描述更具体
忽略正文	只遵循描述	从描述中移除流程/工作流内容
输出不一致	不同会话中的输出各异	添加明确的模板、减少自由度、添加脚本
速度太慢	上下文过长	将详细内容移至 references/，将正文缩减至 500 行以下

改进思路

1. 从反馈中总结规律。 你正在针对少数几个示例进行迭代，但这项技能将用于数千条提示词。不要过度拟合——避免为某个测试用例打过多补丁或设置苛刻的 MUST 规则。不妨尝试不同的比喻或模式
2. 保持提示词精简。 阅读对话记录，而不只是看输出。如果这项技能让模型把时间浪费在无效步骤上，就删掉相关指令，看看效果如何
3. 解释原因。 大模型有很强的心智理论能力。与其用大写字母写 ALWAYS/NEVER，不如解释背后的理由——这样更有力、更稳健。如果你正在编写僵硬的规则，就把它们改写成解释
4. 寻找重复劳动。 如果所有测试运行都会各自编写同一个辅助脚本，就把它放进 scripts/。这样今后的每次调用都不必重新发明轮子
5. 遵循作者准则。 阅读 references/sop-practices.md——其中的 10 条通用原则直接对应技能的失效模式：流程泄漏到描述中、SKILL.md 臃肿而非起到索引作用、环境变量/密钥被内联、缺少“为什么”导致静默发挥、遗漏边缘情况、Agent 跳过文档末尾的检查清单，以及规则形式与其要解决的失效模式不匹配。对于流程类技能（工单、报价、升级处理），还要遵循同一文件中的深度 SOP 方法论

第 2 步：评估迭代循环

改进循环与 CREATE 第 6 步类似，但重点在于修复失效行为。每个候选措辞进入循环前都要进行微型测试；如果技能会强制执行某项规则，则重新运行压力测试场景 → references/pressure-testing.md。

1. 使用当前技能运行失败用例 → 记录失败情况
2. 使用 CREATE 第 5 步的写作规则进行修复
3. 再次运行评估 → 使用 agents/grader.md 评分
4. 启动查看器：uv run eval-viewer/generate_review.py <workspace>
   • 无头模式/Cowork： 使用 --static <output.html>，而不是实时服务
5. 审查、提供反馈并迭代

第 3 步：门控式自我更新循环

根据失败的 BinEval 问题推动迭代，而不是凭感觉——并且只根据编辑者从未见过的证据接受修改。完整规则见：references/bineval-method.md § 门控式自我更新循环。

1. 每个会话只冻结一次数据集划分： uv run scripts/split_evals.py evals/evals.json --holdout 0.4 --write <workspace>/split.json — 这是确定性的，并按可选的每项评估 category 进行分层。查看结果后绝不重新划分
2. 对当前版本运行所有评估并评分（见模式 3 阶段 3 和 references/bineval-method.md）→ 收集 failing[]
3. 仅分析 TRAIN 用例中的失败：提供训练对话记录和评分结果，启动 agents/analyzer.md，以生成经过归纳且去重的经验教训。门控检查前不得查看留出集评分
4. 最多应用 3 项原子修改（添加/删除/替换一条规则、一段文字或一行表格；每项修改对应一条经验教训，并加上标签）。不得整体重写——小幅差异才能在门控检查时明确归因
5. 重新运行所有评估。门控条件——仅在满足以下条件时接受： (a) 与父版本相比，留出集断言没有从通过变为失败（只有连续 2 次运行复现的翻转才计入；单次运行存在噪声）；(b) 训练集通过率严格提高；(c) 没有新增失败的关键问题。欢迎留出集表现有所改善，但并非必须——留出集只有 5–8 个用例时，要求改善就等于在测运气
6. 记录每项断言的变化（改善 / 退步 / 持续失败 / 稳定成功）→ benchmark.json 中的 transitions 区块
7. 当训练集 failing[]（或其中的关键子集）为空，或迭代 3 次后，终止。保留已接受版本中留出集通过率最高的版本；若相同，则选择训练集通过率最高的版本

步骤 3b：盲测比较（可选，适用于重大更改）

当你有两个差异明显的版本时：

1. 在相同的评估集上运行两个版本
2. 启动 agents/comparator.md——在不知道哪个技能生成了哪个输出的情况下，针对输出 A 和 B 回答相同的二元问题
3. 比较器报告每个版本各维度的肯定回答率；整体肯定回答率更高者获胜；若打平，则比较关键维度的肯定回答率
4. 启动 agents/analyzer.md——揭晓结果，分析获胜版本胜出的原因
5. 将分析结果用于改进落败版本

这样可以避免偏见。比较器评判的是输出质量，而非技能设计。

---

模式 3：VALIDATE

分三个阶段，按顺序运行。

阶段 1：结构验证

uv run scripts/eval_skill.py <skill-folder>

检查项：frontmatter、命名、描述质量、流程泄漏检测、正文大小、结构、脚本。目标：10/10，无警告。

阶段 2：发现（触发测试）

生成 6 条测试提示词：

• 3 条应该触发该技能
• 3 条不应该触发（听起来相似，但属于错误领域）

在干净会话中逐条运行。目标：6/6 正确。

如需大规模自动化触发测试，请使用：

uv run scripts/run_eval.py --eval-set <path> --skill-path <path> --runs-per-query 3

阶段 3：BinEval 评分

使用涵盖 5 个维度的原子化二元是/否问题进行评估——每个问题都要在书面评述中引用证据后，回答 1/0。方法见 references/bineval-method.md，问题库见 references/quality-questions.md，会生成 bineval.json 的评估器见 agents/bineval.md。

5 个维度：发现、清晰度、结构、稳健性、完整性。

技能产物的问题来自两个来源（question_source: "hybrid"）：

• 确定性问题——由 scripts/eval_skill.py --json（唯一的生成器）生成，例如 DET-STRUCT-SKILLMD-EXISTS、DET-DISCOVERY-DESC-PRESENT。其中一些标记为关键问题。
• 固定问题库——references/quality-questions.md 中的带版本 LLM 问题；评审器回答这些问题，不得自行编造问题。（通过两步元提示词为每项任务生成的问题，属于模式 1–2 中 agents/grader.md 的输出评分，不属于产物评分。）

评审器只回答问题。由你汇总：每个维度的 dimension_scores S_d = 该维度所有答案的平均值；总体 S = 所有答案的平均值。绝不要在评审器提示词中加入评分等级或 GATE——知道门槛的评审器会倾向于迎合它（references/bineval-method.md）。

显示等级： S≥0.90 可用于生产 · 0.70–0.89 良好 · 0.50–0.69 需要改进 · <0.50 重写。

GATE = 每个关键问题（确定性问题 + 问题库中的关键问题）的答案均为 1。GATE 是通过标准，而非标量 S。

---

模式 4：REVIEW

第三方技能的快速质量门槛检查。

检查清单（通过/失败）

[ ] SKILL.md exists, exact case
[ ] Valid YAML frontmatter (name + description)
[ ] name: kebab-case, matches folder, ≤64 chars
[ ] description: ≤1024 chars, no angle brackets
[ ] description has triggers ("Use when...")
[ ] description has NO workflow/process steps
[ ] No README.md inside skill folder
[ ] SKILL.md < 500 lines
[ ] References max 1 level deep
[ ] Scripts tested and executable
[ ] No hardcoded paths/tokens/secrets

然后对描述运行 VALIDATE 阶段 2（发现测试）。报告得分和检查清单结果。

该检查清单中的确定性子集由 scripts/eval_skill.py --json 生成为二元 BinEval 问题记录（例如 DET-STRUCT-SKILLMD-EXISTS、DET-DISCOVERY-DESC-PRESENT、DET-ROBUST-NO-SECRETS）——它是这些记录的唯一生成器。

之所以需要该检查清单，是因为这些故障模式在实际中确实会发生，尤其是描述中的流程说明，这会导致 Agent 完全跳过正文。

---

模式 5：OPTIMIZE

自动优化描述。该描述需要与其他技能竞争 Claude 的注意力——优化可找出触发最准确的措辞。现在，同样的训练集/留出集原则也适用于正文编辑——参见模式 2 步骤 3。

工作原理

1. 创建一个评估集：20 条查询（10 条应该触发，10 条不应该触发）

编写优质评测查询

查询必须贴近实际——具体、详细，包含文件路径、上下文、缩写和拼写错误。不要写 "Format this data"，而要写 "my boss sent Q4 sales final FINAL v2.xlsx, add profit margin % column, revenue is col C costs col D"。

应触发（10 条）： 用不同说法表达相同意图——正式、随意、含蓄。包含用户没有提及技能名称、但显然需要该技能的情况。添加与其他技能容易混淆的边界案例。

不应触发（10 条）： 看似相近、共享关键词，但实际需要其他处理方式的查询。相邻领域、含义模糊的表述。对 PDF 技能来说，"Write fibonacci" 这样的负例毫无用处——太简单了。负例要真正棘手。

触发机制： Claude 只会在无法直接处理任务时才查阅技能。简单的查询（如 "read this PDF"）无论描述如何，都不会触发技能——Claude 可以用基础工具处理。评测查询必须足够复杂，复杂到查阅技能确实有帮助。

2. 在浏览器中查看查询：assets/eval_review.html
3. 运行优化循环：

uv run scripts/run_loop.py \
  --eval-set evals/eval_set.json \
  --skill-path <skill-dir> \
  --model <model-id> \
  --max-iterations 5 \
  --holdout 0.4 \
  --verbose

优化循环：

• 将查询拆分为训练集（60%）和留出集（40%），以防过拟合
• 每轮迭代：评估当前描述 → Claude 提出改进方案 → 重新评估
• 改进模型只能看到训练结果（对留出集结果盲测）
• 根据留出集得分选择最佳描述
• 自动打开实时 HTML 报告

辅助脚本

脚本	用途
scripts/run_eval.py	根据描述运行触发评估
scripts/improve_description.py	Claude 提出改进后的描述
scripts/generate_report.py	将优化历史可视化为 HTML
scripts/aggregate_benchmark.py	对基准测试运行结果进行统计汇总

---

模式 6：打包

1. 运行审核清单（模式 4）
2. 验证：

uv run scripts/quick_validate.py <skill-folder>

3. 打包：

uv run scripts/package_skill.py <skill-folder> [output-dir]

创建 skill-name.skill（扩展名为 .skill 的 zip 文件）。验证：在临时目录中解压，并检查目录结构是否完整。

---

快速参考

技能类别

1. 文档/资源创建——输出一致（文档、设计、代码）
2. 工作流自动化——采用方法论的多步骤流程
3. MCP 增强——在工具访问能力之上提供工作流指导
4. 程序性 / 流程类——包含决策节点和例外情况的业务流程（处理请求、生成报价、处理发票、入职引导、升级处理）。对于这类技能 → 阅读 references/sop-practices.md

文件用途

目录	是否加载？	用途
SKILL.md	触发时	核心——说明
references/	按需	详细文档、架构
scripts/	执行，不加载	确定性操作
assets/	从不加载	模板、图片

渐进式披露预算

层级	加载时机	预算
Frontmatter	始终（系统提示词）	约 100 个词
SKILL.md 正文	触发时	少于 500 行
捆绑资源	按需	不限

描述公式

[功能说明] + Use when [用户实际会说的 4-5 种表达] + even if they don't explicitly say "<canonical term>" + Do NOT use for [负例]——完整规则和示例见 references/sop-practices.md 原则 #2。

参考文件

按需在各模式指定的使用步骤加载，绝不一次性全部加载。仅在生成对应 Agent 时加载 agents/* 文件；仅在编写或读取 JSON 文件时加载 references/schemas.md。其他文件保持未加载状态。

路径	内容
agents/grader.md	基于证据的断言评分
agents/comparator.md	盲测 A/B 输出比较
agents/analyzer.md	事后分析 + 基准测试备注
agents/bineval.md	BinEval 评估器 — 输出 bineval.json
references/patterns.md	5 种架构模式 + 反模式
references/schemas.md	评估、评分、基准测试的 JSON 架构
references/bineval-method.md	BinEval 方法：维度、评分、GATE
references/quality-questions.md	BinEval 问题库（确定性 + 题库）
references/pressure-testing.md	措辞微测 + 纪律型技能的压力场景
references/sop-practices.md	规范：10 条通用编写原则 + 流程型技能的深入 SOP 方法论
references/runtime-setup.md	预检：uv/env/path 检查、LLM 访问选项
eval-viewer/	用于查看评估结果的交互式 HTML 查看器
assets/eval_review.html	触发评估集编辑器
scripts/eval_skill.py	结构验证（10 分制评分）
scripts/init_skill.py	技能脚手架
scripts/run_eval.py	触发评估运行器
scripts/run_loop.py	评估 + 改进优化循环
scripts/improve_description.py	由 Claude 驱动的描述改进
scripts/aggregate_benchmark.py	基准测试统计聚合器
scripts/generate_report.py	HTML 报告生成器
scripts/quick_validate.py	供打包器使用的快速验证
scripts/test_smoke.py	所有脚本的冒烟测试（12 项测试）
scripts/package_skill.py	Skill → .skill 打包器
scripts/utils.py	共享工具（parse_skill_md）