kc-beta 0.8.1 → 0.8.3

package/template/skills/zh/skill-creator/SKILL.md

@@ -1,12 +1,16 @@
 ---
 name: skill-creator
 tier: meta
-description: Anthropic's skill-scaffolding toolkit — use for iterating/improving existing skills or running evals on them, NOT as the primary reference for building KC's per-rule verification skills. For KC rule skills, consult `skill-authoring` first (canonical folder layout + granularity rules + KC-specific check.py entry-point conventions) and `work-decomposition` for ordering + grouping decisions. This skill applies once per-rule skills exist and the agent wants to optimize their description/triggering or run formal evals.
+description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
 ---
 
-# Skill Creator
+# Skill creator（KC 兜底）
 
-一个用于创建新技能并对其进行迭代改进的技能。它既覆盖从零创建技能的全流程，也覆盖在已有技能基础上做小幅改进、跑回归评估的场景。
+这是 Anthropic 上游 `skill-creator` 方法论的中文版，作为编写复杂技能时的深度参考随 KC 一并发布。KC 内部主流的技能编写路径是 `skill-authoring` 技能（核心思想沿袭自本技能）。只有当 `skill-authoring` 的指引对你正在编写的技能复杂度而言不够用时，才直接来查阅 `skill-creator`——例如你想跑正式的评估循环、做带方差分析的基准对比，或对触发用的 description 做优化。关于"先做哪些技能、怎样分组"的决策，请参考 `work-decomposition`。
+
+---
+
+一个用于创建新技能并对其进行迭代改进的技能。
 
 从高层次看，创建一个技能的流程大致如下：
 
@@ -20,26 +24,26 @@ description: Anthropic's skill-scaffolding toolkit — use for iterating/improvi
 - 反复迭代，直到满意为止
 - 扩充测试集，在更大规模上再跑一遍
 
-使用这个技能时，你的工作是判断用户目前处在上述流程的哪个阶段，然后从那里切入帮他们继续推进。比如，用户可能说"我想做一个 X 的技能"，你就可以帮他们澄清需求、写初稿、写测试用例、确定评估方式、跑完所有提示词、再迭代。整套流程并不是一条单向直线，而是一个不断反复回到上一步的小循环——每写一版，都通过观察实际跑出来的产物来校准下一版的指令。
+使用这个技能时，你的工作是判断用户目前处在上述流程的哪个阶段，然后从那里切入帮他们继续推进。比如，用户可能说"我想做一个 X 的技能"。你就可以帮他们澄清需求、写初稿、写测试用例、确定评估方式、跑完所有提示词、再迭代。
 
-另一种情况是，他们已经有一个技能初稿。这时你可以直接跳到评估/迭代那一段循环，不必把前面的"澄清意图"再走一遍——但即便已经跳过了访谈环节，仍然有必要在心里复盘一下："这个技能想解决的核心问题到底是什么？"再带着这个问题去看现有初稿，往往能马上发现一些可以收紧或扩展的地方。
+另一种情况是，他们已经有一个技能初稿。这时你可以直接跳到评估/迭代那一段循环。
 
-当然，你应当保持灵活。如果用户说"我不想跑一堆评估，咱们就随意一点感觉感觉"，那就这样做也没问题。本技能描述的是一条经过沉淀的"完整路径"，但路径不是教条——根据用户的偏好和当下的时间预算去裁剪是允许的。
+当然，你应当保持灵活。如果用户说"我不想跑一堆评估，咱们就随意一点感觉感觉"，那就这样做也没问题。
 
-技能基本完成之后（顺序仍然是灵活的），你还可以运行技能描述优化器——我们为此专门写了一个脚本——来优化技能的触发表现。Description 写得好不好，直接决定了在真实场景里它会不会被调用；优化这一步常常被忽视，但收益往往很大。
+技能基本完成之后（顺序仍然是灵活的），你还可以运行技能描述优化器——我们为此专门写了一个脚本——来优化技能的触发表现。
 
 可以了吧？可以了。
 
 ## 与用户沟通
 
-skill creator 的使用者可能跨越从对编程行话非常陌生到相当熟悉的整个区间。如果你没听说过的话（也很正常，这个趋势也才刚出现没多久），现在出现了一股潮流：Claude 的能力激发着水管工去打开终端、爸爸妈妈和爷爷奶奶去 google "怎么安装 npm"。不过绝大多数用户应该还是对计算机比较熟悉的。这意味着默认假设可以稍微偏向"有一定计算机基础"那一侧，但你要随时准备根据对方的提问方式和表述习惯往任意方向调整。
+skill creator 的使用者可能跨越从对编程行话非常陌生到相当熟悉的整个区间。如果你没听说过的话（也很正常，这个趋势也才刚出现没多久），现在出现了一股潮流：Claude 的能力激发着水管工去打开终端、爸爸妈妈和爷爷奶奶去 google "怎么安装 npm"。不过绝大多数用户应该还是对计算机比较熟悉的。
 
 所以请关注上下文线索，据此判断该如何措辞！默认情况下大概可以这样把握尺度：
 
 - "evaluation" 和 "benchmark" 处于临界状态，但通常可以直接用
 - 对于 "JSON" 和 "assertion"，则要看到用户给出明确信号、表明他们了解这些概念之后，再直接使用、不加解释
 
-如果拿不准，简短地解释一下术语也完全可以；只要担心用户可能不懂，就顺手给一个一句话的定义。一句额外的解释让懂行的人浪费一秒钟，但能让不懂的人少卡半天，这笔账几乎总是合算的。同样，遇到对方明显在用专业语汇时，也不必再为已经熟练的概念多做铺垫——那样反而会显得啰嗦、低估对方。
+如果拿不准，简短地解释一下术语也完全可以；只要担心用户可能不懂，就顺手给一个一句话的定义。
 
 ---
 
@@ -47,7 +51,7 @@ skill creator 的使用者可能跨越从对编程行话非常陌生到相当熟
 
 ### 捕捉意图
 
-先从理解用户的意图开始。当前对话里可能已经包含了用户想要沉淀为技能的工作流程（例如他们说"把这个变成一个技能"）。如果是这种情况，先从对话历史中提取答案——用过哪些工具、步骤的顺序、用户做过哪些修正、观察到的输入/输出格式。剩下的缺口由用户来补齐，并在进入下一步之前请他们确认。把这些信息汇总出来再回放一遍给用户看，往往能立刻暴露出双方理解上的偏差，便于早点对齐。
+先从理解用户的意图开始。当前对话里可能已经包含了用户想要沉淀为技能的工作流程（例如他们说"把这个变成一个技能"）。如果是这种情况，先从对话历史中提取答案——用过哪些工具、步骤的顺序、用户做过哪些修正、观察到的输入/输出格式。剩下的缺口由用户来补齐，并在进入下一步之前请他们确认。
 
 1. 这个技能应该让 Claude 能做什么？
 2. 这个技能应该在什么时候触发？（什么样的用户话术/语境）
@@ -56,16 +60,16 @@ skill creator 的使用者可能跨越从对编程行话非常陌生到相当熟
 
 ### 访谈与调研
 
-主动询问关于边界情况、输入/输出格式、示例文件、成功标准和依赖项的问题。在把这一部分敲定之前，不要急着写测试提示词。把边界情况和成功标准提前问清楚，可以避免后面反复回炉——技能写完才发现某个关键约束没考虑到，往往要把整段指令重写。
+主动询问关于边界情况、输入/输出格式、示例文件、成功标准和依赖项的问题。在把这一部分敲定之前，不要急着写测试提示词。
 
-留意可用的 MCP——如果它们对调研有帮助（搜索文档、查找相似技能、了解最佳实践），并且环境支持子代理就并行调研，否则就在主线程内联进行。带着上下文进入，可以减轻用户的负担。一个常见的高价值动作：先快速搜一遍工作区有没有相似的技能，看看它们是怎么组织目录、怎么写 description 的——既能借鉴模式，也能避免重复造轮子。
+留意可用的 MCP——如果它们对调研有帮助（搜索文档、查找相似技能、了解最佳实践），并且环境支持子代理就并行调研，否则就在主线程内联进行。带着上下文进入，可以减轻用户的负担。
 
 ### 编写 SKILL.md
 
 基于对用户的访谈结果，填写以下组成部分：
 
 - **name**：技能标识符
-- **description**：何时触发、做什么。这是最主要的触发机制——既要写技能"做什么"，又要写"什么场景下使用它"的具体描述。所有"何时使用"的信息都放在这里，不要放在正文里。注意：当前 Claude 容易"触发不足"——明明应该用的技能却不调用。为了对冲这种倾向，请把技能描述写得稍微"催促"一点。比如，与其写"用于构建一个简单快速的仪表盘，以展示 Anthropic 内部数据。"，不如写"用于构建一个简单快速的仪表盘，以展示 Anthropic 内部数据。只要用户提到 dashboard、数据可视化、内部指标，或者想要展示任何类型的公司数据，都要使用这个技能，即使他们没有显式说出'dashboard'这个词。"description 字段直接影响可发现性，写得稍微具体一些、把可能出现的同义说法都覆盖到，往往能带来显著的触发率提升。
+- **description**：何时触发、做什么。这是最主要的触发机制——既要写技能"做什么"，又要写"什么场景下使用它"的具体描述。所有"何时使用"的信息都放在这里，不要放在正文里。注意：当前 Claude 容易"触发不足"——明明应该用的技能却不调用。为了对冲这种倾向，请把技能描述写得稍微"催促"一点。比如，与其写"用于构建一个简单快速的仪表盘，以展示 Anthropic 内部数据。"，不如写"用于构建一个简单快速的仪表盘，以展示 Anthropic 内部数据。只要用户提到 dashboard、数据可视化、内部指标，或者想要展示任何类型的公司数据，都要使用这个技能，即使他们没有显式说出 'dashboard' 这个词。"
 - **compatibility**：依赖的工具、依赖项（可选，很少需要）
 - **技能的剩余部分 :)**
 
@@ -91,14 +95,14 @@ skill-name/
 2. **SKILL.md 正文**——技能被触发时进入上下文（理想情况下少于 500 行）
 3. **打包资源**——按需加载（无上限；脚本可以执行而无需被加载进上下文）
 
-这些字数都是大概数字，必要时可以放宽。整体原则是：让"几乎总是要看的内容"在第 1、2 层，让"只在特定子任务里才有用"的内容放到第 3 层，按需引用。这样可以把上下文窗口的开销控制在合理范围内，避免主指令被庞杂的细节淹没。
+这些字数都是大概数字，必要时可以放宽。
 
 **关键模式：**
 - 把 SKILL.md 控制在 500 行以内；如果接近上限，就再加一层目录层级，并清楚地告诉调用该技能的模型"下一步该去哪里"。
 - 在 SKILL.md 中清晰地引用其他文件，并说明何时去读它们
 - 对于较大的参考文件（>300 行），请加上目录
 
-**按领域组织**：当一个技能要支持多个领域/框架时，按变体组织。这种结构的好处是：主 SKILL.md 只负责描述工作流和如何选择合适的参考文件，具体到每种变体的细节交给独立的参考文件。每次调用只会读到当下任务相关的那一份，避免把无关变体的内容也塞进上下文窗口：
+**按领域组织**：当一个技能要支持多个领域/框架时，按变体组织：
 ```
 cloud-deploy/
 ├── SKILL.md (workflow + selection)
@@ -111,7 +115,7 @@ Claude 只会读取相关的那一份参考文件。
 
 #### 不让用户惊讶的原则
 
-这点几乎不言自明，但还是要说：技能不得包含恶意代码、漏洞利用代码，或任何可能危及系统安全的内容。技能的实际内容不应让用户对其意图感到意外——如果你向用户描述这个技能，它的真实行为应该与描述一致。不要配合用户写出误导性的技能，或者用于未授权访问、数据外泄等恶意目的的技能。但像"扮演 XYZ 角色"这种是可以的。判断的核心标准是：把这个技能描述给一个理性的旁观者听，他会不会对实际行为感到震惊？如果会，那这个技能就违反了"不让人惊讶"的原则，应当拒绝创建或要求重写。
+这点几乎不言自明，但还是要说：技能不得包含恶意代码、漏洞利用代码，或任何可能危及系统安全的内容。技能的实际内容不应让用户对其意图感到意外——如果你向用户描述这个技能，它的真实行为应该与描述一致。不要配合用户写出误导性的技能，或者用于未授权访问、数据外泄等恶意目的的技能。但像"扮演 XYZ 角色"这种是可以的。
 
 #### 写作模式
 
@@ -137,11 +141,11 @@ Output: feat(auth): implement JWT-based authentication
 
 ### 写作风格
 
-尽量向模型解释清楚某件事情为什么重要，而不是堆砌生硬死板的"必须 MUST"。运用心智理论，把技能写得通用一些，而不是死扣具体例子。先写一版初稿，然后过一段时间用全新的眼光重新审视、加以改进。一个常见的反模式是：用某个具体场景的细节去定义抽象规则——结果遇到稍微偏离的场景就失灵。要写得既具体到能落地、又通用到能迁移，确实需要反复打磨。
+尽量向模型解释清楚某件事情为什么重要，而不是堆砌生硬死板的"必须 MUST"。运用心智理论，把技能写得通用一些，而不是死扣具体例子。先写一版初稿，然后过一段时间用全新的眼光重新审视、加以改进。
 
 ### 测试用例
 
-写完技能初稿后，准备 2–3 条贴近实际的测试提示词——也就是真实用户实际可能说出的话。把它们摆给用户看：[不必照搬这段措辞]"这里有几条我想跑一下的测试用例，看着合适吗？还要再加几条吗？"然后就去跑。挑选用例时，可以兼顾"代表性场景"和"会暴露问题的边界情况"——前者验证技能在主流路径上能工作，后者帮你尽早发现写法上的漏洞。
+写完技能初稿后，准备 2–3 条贴近实际的测试提示词——也就是真实用户实际可能说出的话。把它们摆给用户看：[不必照搬这段措辞]"这里有几条我想跑一下的测试用例，看着合适吗？还要再加几条吗？"然后就去跑。
 
 把测试用例保存到 `evals/evals.json`。这一步先不写断言（assertion），只写提示词。断言会在下一步、运行测试的过程中起草。
 
@@ -163,16 +167,14 @@ Output: feat(auth): implement JWT-based authentication
 
 ## 运行并评估测试用例
 
-这一节是一个连续的整体——不要中途停下。不要使用 `/skill-test` 或任何其他测试用的技能。把它当成一段连贯的工作流：启动、抓数据、打分、汇总、给人看，中间任何一段断开了都会让最终评审失去价值。
+这一节是一个连续的整体——不要中途停下。不要使用 `/skill-test` 或任何其他测试用的技能。
 
-把结果放在 `<skill-name>-workspace/` 下，与技能目录平级。在 workspace 内部，按迭代分组（`iteration-1/`、`iteration-2/` 等），每个测试用例再各占一个目录（`eval-0/`、`eval-1/` 等）。不必一开始就把所有目录建好——边做边建即可。这种目录约定让多次迭代之间的对比变得自然：以后只要把 `--previous-workspace` 指向上一轮，就能把两轮结果摆在一起看。
+把结果放在 `<skill-name>-workspace/` 下，与技能目录平级。在 workspace 内部，按迭代分组（`iteration-1/`、`iteration-2/` 等），每个测试用例再各占一个目录（`eval-0/`、`eval-1/` 等）。不必一开始就把所有目录建好——边做边建即可。
 
 ### 第 1 步：在同一轮里启动全部运行（with-skill 与 baseline）
 
 针对每个测试用例，在同一轮里启动两个子代理——一个带技能，一个不带。这一点很重要：不要先把 with-skill 的那一轮全跑完、之后再回来补 baseline。所有任务一次性启动，让它们大约同时完成。
 
-这种并行启动的安排不光是为了"省时间"——更重要的是保证两路运行处于尽可能相近的执行环境下（同一段时间窗口、同一组后端负载），减少由"先跑后跑"引入的系统性偏差。
-
 **带技能的运行：**
 
 ```
@@ -203,9 +205,9 @@ Execute this task:
 
 不要光等运行结束——这段时间可以利用起来。为每个测试用例起草定量断言，并向用户解释这些断言。如果 `evals/evals.json` 里已经有断言，过一遍并向用户说明每条检查的是什么。
 
-好的断言是客观可验证的，并且名字有描述性——在基准查看器里一眼就能看出每条到底在检查什么。主观性的技能（写作风格、设计质感）更适合做定性评估——不要硬把断言套到需要人类判断的事情上。一个简单判别准则：如果你都要犹豫一下"这条算通过吗？"，那这条多半应该改成定性评审。
+好的断言是客观可验证的，并且名字有描述性——在基准查看器里一眼就能看出每条到底在检查什么。主观性的技能（写作风格、设计质感）更适合做定性评估——不要硬把断言套到需要人类判断的事情上。
 
-起草完之后，把断言更新进 `eval_metadata.json` 和 `evals/evals.json`。同时也告诉用户他们会在查看器里看到什么——既包括定性的输出，也包括定量的基准指标。这样用户在打开页面之前就有心理预期，不至于看到陌生界面再花时间摸索。
+起草完之后，把断言更新进 `eval_metadata.json` 和 `evals/evals.json`。同时也告诉用户他们会在查看器里看到什么——既包括定性的输出，也包括定量的基准指标。
 
 ### 第 3 步：随着任务完成抓取计时数据
 
@@ -219,7 +221,7 @@ Execute this task:
 }
 ```
 
-这是你抓取这些数据的唯一机会——它们随任务通知一起来，并不会被持久化到别的地方。请收到一条就处理一条，不要等着攒一批再处理。如果错过了这一次，后面再想恢复就只能重跑——这不仅浪费 token，也会引入新的运行随机性，导致前后对比失真。养成"通知一到就立刻落盘"的习惯。
+这是你抓取这些数据的唯一机会——它们随任务通知一起来，并不会被持久化到别的地方。请收到一条就处理一条，不要等着攒一批再处理。
 
 ### 第 4 步：评分、汇总、并启动查看器
 
@@ -247,7 +249,7 @@ Execute this task:
    ```
    到第 2 次及以后的迭代，还要加上 `--previous-workspace <workspace>/iteration-<N-1>`。
 
-   **Cowork / 无界面环境：**如果 `webbrowser.open()` 不可用，或者环境根本没有显示器，请用 `--static <output_path>` 来生成一份独立的 HTML 文件，而不是启动服务器。用户点击 "Submit All Reviews" 时反馈会被下载为 `feedback.json` 文件。下载之后，把 `feedback.json` 拷进 workspace 目录，下一轮迭代会读取它。
+   **Cowork / 无界面环境：** 如果 `webbrowser.open()` 不可用，或者环境根本没有显示器，请用 `--static <output_path>` 来生成一份独立的 HTML 文件，而不是启动服务器。用户点击 "Submit All Reviews" 时反馈会被下载为 `feedback.json` 文件。下载之后，把 `feedback.json` 拷进 workspace 目录，下一轮迭代会读取它。
 
 注意：请使用 generate_review.py 来生成查看器；没必要手写 HTML。
 
@@ -284,7 +286,7 @@ Execute this task:
 
 反馈为空意味着用户觉得没问题。请把改进精力集中在那些用户提出了具体意见的测试用例上。
 
-事情做完之后记得把查看器服务进程关掉，避免端口和资源被一直占用——尤其是在你打算同一天内开下一轮迭代或同时调试多个技能的时候：
+事情做完之后记得把查看器服务进程关掉：
 
 ```bash
 kill $VIEWER_PID 2>/dev/null
@@ -294,17 +296,17 @@ kill $VIEWER_PID 2>/dev/null
 
 ## 改进技能
 
-这一段是整个循环的核心。你跑完了测试用例，用户也评审了结果，接下来要根据他们的反馈把技能做得更好。这一步看起来"只是改文档"，但实际上是整个流程里最考验功力的一段——前面所有的运行和评分，价值就体现在它们如何指导你这里的每一次修改。
+这一段是整个循环的核心。你跑完了测试用例，用户也评审了结果，接下来要根据他们的反馈把技能做得更好。
 
 ### 怎样思考改进
 
-1. **从反馈中泛化。** 这里大局上要明白的是：我们想做的是能被使用上百万次（也许字面意义上、甚至更多次，谁知道呢）、横跨各种各样提示词的技能。眼下你和用户只是反复在少数几个例子上迭代，因为这样推进得快。这些例子用户烂熟于心，新输出他们一眼就能评估。但如果你和用户共同开发出来的技能只在这几个例子上管用，那就毫无意义。与其塞进各种过拟合的小补丁、或者堆上一堆压迫性的 MUST，不如在遇到某个顽固问题时换条路子：尝试新的比喻、推荐不一样的工作模式。试一下成本很低，说不定就撞到一个特别好的写法。换个角度说：你的真正客户不是当前评审的这几个测试用例，而是未来千千万万个还没见过的真实请求；改写时要时不时把自己拉回这个视角。
+1. **从反馈中泛化。** 这里大局上要明白的是：我们想做的是能被使用上百万次（也许字面意义上、甚至更多次，谁知道呢）、横跨各种各样提示词的技能。眼下你和用户只是反复在少数几个例子上迭代，因为这样推进得快。这些例子用户烂熟于心，新输出他们一眼就能评估。但如果你和用户共同开发出来的技能只在这几个例子上管用，那就毫无意义。与其塞进各种过拟合的小补丁、或者堆上一堆压迫性的 MUST，不如在遇到某个顽固问题时换条路子：尝试新的比喻、推荐不一样的工作模式。试一下成本很低，说不定就撞到一个特别好的写法。
 
-2. **保持提示词精简。** 把那些没在出力的内容删掉。除了看最终输出，请务必读一下完整的 transcript——如果发现技能让模型在无谓的事情上浪费时间，可以试着去掉造成这种浪费的部分，看看效果。很多时候技能越精简、模型反而表现越好：冗余指令会拖偏注意力，过于细碎的步骤会让模型陷入按部就班、丧失判断力。
+2. **保持提示词精简。** 把那些没在出力的内容删掉。除了看最终输出，请务必读一下完整的 transcript——如果发现技能让模型在无谓的事情上浪费时间，可以试着去掉造成这种浪费的部分，看看效果。
 
-3. **解释"为什么"。** 努力把你要求模型做的每件事背后的**原因**讲清楚。今天的 LLM 是*聪明*的。它们有不错的心智理论，在有好用的引导框架时能跳出机械执行、把事情真正做成。即使用户的反馈很简短、甚至带着不耐烦，也要努力理解任务本身，理解用户为什么这样写、他们究竟写了什么，然后把这种理解传递到指令里去。如果你发现自己在用大写 ALWAYS 或 NEVER、或者用上特别死板的结构，那是个黄色警示——尽可能换种说法，把背后的道理讲明白，让模型理解你为什么要求做这件事。这样更人性、也更有力、更有效。一个粗略的检验标准：把改完的句子读一遍，问问自己"如果我是被这条指令约束的模型，我能理解这条规则的目的是什么吗？"如果答案是不能，那就意味着指令还不够好。
+3. **解释"为什么"。** 努力把你要求模型做的每件事背后的**原因**讲清楚。今天的 LLM 是*聪明*的。它们有不错的心智理论，在有好用的引导框架时能跳出机械执行、把事情真正做成。即使用户的反馈很简短、甚至带着不耐烦，也要努力理解任务本身，理解用户为什么这样写、他们究竟写了什么，然后把这种理解传递到指令里去。如果你发现自己在用大写 ALWAYS 或 NEVER、或者用上特别死板的结构，那是个黄色警示——尽可能换种说法，把背后的道理讲明白，让模型理解你为什么要求做这件事。这样更人性、也更有力、更有效。
 
-4. **留意各个测试用例之间的重复劳动。** 阅读测试运行的 transcript，留意几个子代理是不是都各自独立写了类似的辅助脚本、或者走了同样的多步流程。如果 3 个测试用例里子代理都各自写了一个 `create_docx.py` 或 `build_chart.py`，那就是一个很强的信号：这个技能应该把那段脚本打包进来。写一次，放到 `scripts/`，然后让技能去调用它。这样以后每次调用都不必从零再造一遍。这种"重复劳动抽离"的好处不仅在于省 token，更在于把质量稳定性提了一个数量级——脚本写一次就一直按预期工作，不依赖每次调用时模型是否"想到"按某种方式去做。
+4. **留意各个测试用例之间的重复劳动。** 阅读测试运行的 transcript，留意几个子代理是不是都各自独立写了类似的辅助脚本、或者走了同样的多步流程。如果 3 个测试用例里子代理都各自写了一个 `create_docx.py` 或 `build_chart.py`，那就是一个很强的信号：这个技能应该把那段脚本打包进来。写一次，放到 `scripts/`，然后让技能去调用它。这样以后每次调用都不必从零再造一遍。
 
 这项任务相当重要（我们可是想在这上面每年创造数十亿美元的经济价值！），而思考时间从来不是瓶颈；请慢慢来，反复琢磨。我建议先写一版修订稿，然后用全新的眼光再看一遍，进一步打磨。真的努力站到用户的位置，去理解他们想要什么、需要什么。
 
@@ -313,7 +315,7 @@ kill $VIEWER_PID 2>/dev/null
 改完技能之后：
 
 1. 把改进应用到技能上
-2. 把所有测试用例都重新跑一遍，写到一个新的 `iteration-<N+1>/` 目录里，也包括 baseline 运行。如果你在做的是创建新技能，baseline 一直是 `without_skill`（不带任何技能）——这在所有迭代里保持不变。如果你在改进已有技能，那么用哪种作为 baseline 由你判断：用户最初带进来的原始版本，还是上一轮迭代的版本。前者能体现"自起点以来"的累计改进，后者能体现"这一轮"是不是真的更好；两种视角各有用处，可以根据用户的关注点来选。
+2. 把所有测试用例都重新跑一遍，写到一个新的 `iteration-<N+1>/` 目录里，也包括 baseline 运行。如果你在做的是创建新技能，baseline 一直是 `without_skill`（不带任何技能）——这在所有迭代里保持不变。如果你在改进已有技能，那么用哪种作为 baseline 由你判断：用户最初带进来的原始版本，还是上一轮迭代的版本。
 3. 启动评审器，并把 `--previous-workspace` 指向前一次迭代
 4. 等用户评审完、告诉你结束为止
 5. 读取新的反馈，再改进，再迭代
@@ -323,25 +325,23 @@ kill $VIEWER_PID 2>/dev/null
 - 所有反馈都为空（全都看着没问题）
 - 你已经不再做出有意义的进展
 
-注意到第三条："不再做出有意义的进展"是一个真实存在的终止状态——并不是每一轮迭代都必然带来改进。当你发现新一版主要是在"换个说法"或者"在某个例子上略微更好、在另一个例子上略微更差"，那很可能就是接近天花板的信号；此时应该明说出来，让用户决定是收工还是改换思路（比如扩展测试集、加入完全不同的用例）。
-
 ---
 
 ## 进阶：盲对比
 
-在需要对一个技能的两个版本做更严格比较的情况下（比如用户问"新版本到底是不是真的更好？"），有一套盲对比体系。详情请读 `agents/comparator.md` 和 `agents/analyzer.md`。基本思路是：把两份输出交给一个独立代理、但不告诉它哪份是哪份，让它来评判质量。然后再分析"赢的那份为什么赢"。盲对比的最大价值在于剔除位置偏差和"我知道哪份是新版"造成的潜在偏见，从而得到一个更接近双盲实验的判断；当两版差距比较细微时，这一招尤其管用。
+在需要对一个技能的两个版本做更严格比较的情况下（比如用户问"新版本到底是不是真的更好？"），有一套盲对比体系。详情请读 `agents/comparator.md` 和 `agents/analyzer.md`。基本思路是：把两份输出交给一个独立代理、但不告诉它哪份是哪份，让它来评判质量。然后再分析"赢的那份为什么赢"。
 
-这个步骤是可选的，需要子代理，多数用户用不到。人工评审循环通常已经够用。把盲对比当作"特殊场合的工具"而不是默认流程：当你和用户都觉得"这一轮改动看起来差不多，但不太确定"，再启用它来取得一个更客观的判定。
+这个步骤是可选的，需要子代理，多数用户用不到。人工评审循环通常已经够用。
 
 ---
 
 ## 描述优化
 
-SKILL.md 前置元信息（frontmatter）里的 description 字段是决定 Claude 是否调用一个技能的主要机制。在创建或改进一个技能之后，可以主动提议优化它的 description，以提升触发的准确性。一个写得很棒、但触发条件含糊的技能，在真实生产里的命中率可能远低于预期；description 优化的目的就是把"该触发时一定触发、不该触发时一定不触发"这件事系统化地校准好。
+SKILL.md 前置元信息（frontmatter）里的 description 字段是决定 Claude 是否调用一个技能的主要机制。在创建或改进一个技能之后，可以主动提议优化它的 description，以提升触发的准确性。
 
 ### 第 1 步：生成触发评估查询
 
-写出 20 条 eval 查询——里面既有"应当触发"的，也有"不应当触发"的。20 条不是硬性下限，但太少（比如 5–6 条）就很难体现统计意义上的差异；太多（>40）则每轮跑下来太慢，迭代效率下降。保存为 JSON：
+写出 20 条 eval 查询——里面既有"应当触发"的，也有"不应当触发"的。保存为 JSON：
 
 ```json
 [
@@ -364,7 +364,7 @@ SKILL.md 前置元信息（frontmatter）里的 description 字段是决定 Clau
 
 ### 第 2 步：与用户一起评审
 
-用 HTML 模板把这套 eval 集合呈给用户评审。用户对自己实际使用场景的把握远胜于你——他们会一眼看出哪些查询根本不像真实输入、哪些标签可能反了。这一轮评审越认真，后面优化循环出来的 description 就越靠谱：
+用 HTML 模板把这套 eval 集合呈给用户评审：
 
 1. 从 `assets/eval_review.html` 读取模板
 2. 替换占位符：
@@ -379,7 +379,7 @@ SKILL.md 前置元信息（frontmatter）里的 description 字段是决定 Clau
 
 ### 第 3 步：运行优化循环
 
-告诉用户："这个会花一点时间——我会在后台跑优化循环，并定期回来看看进展。"明确这是个长流程很重要——不然用户可能以为对话卡住了；提前打预防针可以避免不必要的焦虑。
+告诉用户："这个会花一点时间——我会在后台跑优化循环，并定期回来看看进展。"
 
 把 eval 集合保存到 workspace，然后在后台运行：
 
@@ -396,23 +396,23 @@ python -m scripts.run_loop \
 
 它运行期间，请周期性地 tail 一下输出，向用户汇报当前是第几轮迭代、得分是什么样子。
 
-它会自动完成整个优化循环。它会把 eval 集合按 60% 训练 / 40% 留出测试拆开，先评估当前 description（每条查询跑 3 次以得到稳定的触发率），再调用带扩展思考的 Claude 根据失败用例提出改进建议。它会在新 description 上重新跑训练集和测试集，最多迭代 5 轮。结束时，它会在浏览器里打开一份 HTML 报告，展示每一轮的结果，并返回包含 `best_description` 的 JSON——是按测试集得分而不是训练集得分挑出来的，以避免过拟合。
+它会自动完成整个优化循环。它会把 eval 集合按 60% 训练 / 40% 留出测试拆开，先评估当前 description（每条查询跑 3 次以得到稳定的触发率），再调用 Claude 根据失败用例提出改进建议。它会在新 description 上重新跑训练集和测试集，最多迭代 5 轮。结束时，它会在浏览器里打开一份 HTML 报告，展示每一轮的结果，并返回包含 `best_description` 的 JSON——是按测试集得分而不是训练集得分挑出来的，以避免过拟合。
 
 ### 技能触发机制的工作原理
 
 理解触发机制有助于设计更好的 eval 查询。技能会以 name + description 的形式出现在 Claude 的 `available_skills` 列表里，Claude 根据这个 description 决定是否查阅一个技能。一个要点是：Claude 只会在它自己很难独立完成的任务上去查阅技能——像"读一下这份 PDF"这种简单的一步式查询可能并不会触发技能，哪怕 description 完美匹配，因为 Claude 用基础工具就能直接处理。复杂的、多步骤的、或者专业性强的查询，在 description 匹配的前提下能够可靠地触发技能。
 
-这意味着你的 eval 查询要足够有分量，让 Claude 真的能从查阅技能中获益。"读一下文件 X"这种简单查询不是好的测试用例——不管 description 写得多好，它们都不会触发技能。换句话说：description 的优化只能解决"应当触发但没触发"和"不应触发但触发了"这两类问题；至于"太简单以至于本来就不会触发"的查询，那是测试用例本身的问题，不该背在 description 头上。
+这意味着你的 eval 查询要足够有分量，让 Claude 真的能从查阅技能中获益。"读一下文件 X"这种简单查询不是好的测试用例——不管 description 写得多好，它们都不会触发技能。
 
 ### 第 4 步：应用结果
 
-从 JSON 输出里取出 `best_description`，更新技能 SKILL.md 的前置元信息。给用户看一下前后对比，并报告分数。即使分数提升明显，也建议让用户最后定夺——有时优化器选出的描述虽然分数高，但风格上可能与项目其他技能不统一，用户可以决定是否需要做点措辞上的微调。
+从 JSON 输出里取出 `best_description`，更新技能 SKILL.md 的前置元信息。给用户看一下前后对比，并报告分数。
 
 ---
 
 ### 打包与呈现（仅在有 `present_files` 工具时进行）
 
-先检查你是否有 `present_files` 工具。如果没有，跳过这一步。如果有，就把技能打包，并把 .skill 文件呈现给用户。打包动作意味着这一版本可以被独立分发或安装，所以建议只在用户明确表示满意之后再执行——半成品的 .skill 文件流传出去往往会造成困扰：
+先检查你是否有 `present_files` 工具。如果没有，跳过这一步。如果有，就把技能打包，并把 .skill 文件呈现给用户：
 
 ```bash
 python -m scripts.package_skill <path/to/skill-folder>
@@ -424,61 +424,71 @@ python -m scripts.package_skill <path/to/skill-folder>
 
 ## Claude.ai 专用说明
 
-在 Claude.ai 上，核心工作流不变（起草 → 测试 → 评审 → 改进 → 重复），但因为 Claude.ai 没有子代理，一些机制需要相应调整。Claude.ai 环境受限的地方主要在于并行能力、文件系统访问和本地浏览器交互；下面把每个受影响的环节单独列出来，告诉你应该怎样替代。要点如下：
+在 Claude.ai 上，核心工作流不变（起草 → 测试 → 评审 → 改进 → 重复），但因为 Claude.ai 没有子代理，一些机制需要相应调整：
 
-**运行测试用例**：没有子代理就意味着没有并行执行。对每个测试用例，先读技能的 SKILL.md，然后照着它的指示自己来完成测试提示词的任务。一次跑一个。这样的严谨度不如让独立子代理来跑（你既写了技能，也在执行它，会带着完整的上下文），但作为合理性检查仍然有价值——而且人工评审环节会作为补偿。跳过基线运行——就按照用户要求用技能完成任务即可。要意识到这种"自评"模式存在一定偏差：因为你比真实用户更清楚技能的设计意图，结果可能会显得比实际部署时更好，记得在向用户汇报时把这个局限说清楚。
+**运行测试用例**：没有子代理就意味着没有并行执行。对每个测试用例，先读技能的 SKILL.md，然后照着它的指示自己来完成测试提示词的任务。一次跑一个。这样的严谨度不如让独立子代理来跑（你既写了技能，也在执行它，会带着完整的上下文），但作为合理性检查仍然有价值——而且人工评审环节会作为补偿。跳过基线运行——就按照用户要求用技能完成任务即可。
 
-**评审结果**：如果你打不开浏览器（比如 Claude.ai 的 VM 没有显示器，或者你在远端服务器上），那就完全跳过浏览器评审器。改为直接在对话中展示结果。对每个测试用例，展示提示词和输出。如果输出是一个用户需要看的文件（比如 .docx 或 .xlsx），先把它存到文件系统里、再告诉他们路径，让他们下载并查看。在对话中直接征求反馈："看着怎么样？有什么想改的吗？"在对话中评审有个小优势：用户可以就某个具体细节继续追问，而你可以马上回答——这种来回反而比静态网页评审更高效。
+**评审结果**：如果你打不开浏览器（比如 Claude.ai 的 VM 没有显示器，或者你在远端服务器上），那就完全跳过浏览器评审器。改为直接在对话中展示结果。对每个测试用例，展示提示词和输出。如果输出是一个用户需要看的文件（比如 .docx 或 .xlsx），先把它存到文件系统里、再告诉他们路径，让他们下载并查看。在对话中直接征求反馈："看着怎么样？有什么想改的吗？"
 
-**基准化**：跳过定量基准——它依赖的基线比较在没有子代理时本来就没什么意义。把精力放在来自用户的定性反馈上。在没有定量数据的情况下，建议尽量把每次评审都安排得仔细一些——多看几个例子、多问几个具体问题，用质的密度来弥补量的缺失。
+**基准化**：跳过定量基准——它依赖的基线比较在没有子代理时本来就没什么意义。把精力放在来自用户的定性反馈上。
 
 **迭代循环**：和之前一样——改进技能、重跑测试用例、收集反馈——只是中间不走浏览器评审器。如果有文件系统，你仍然可以把结果按迭代目录整理起来。
 
-**Description 优化**：这一节需要 `claude` 命令行工具（具体来说是 `claude -p`），它只在 Claude Code 里可用。如果你在 Claude.ai，就跳过这一节。作为替代方案，你可以人工凭直觉迭代 description，但请如实告诉用户这只是粗略的手工调优、并不等价于优化器跑出来的结果。
+**Description 优化**：这一节需要 `claude` 命令行工具（具体来说是 `claude -p`），它只在 Claude Code 里可用。如果你在 Claude.ai，就跳过这一节。
 
-**盲对比**：需要子代理。跳过。这部分在 Claude.ai 完全无法绕过——它本质上依赖把两路独立运行交给一个第三方代理裁判，没有子代理就没有"独立"可言。
+**盲对比**：需要子代理。跳过。
 
-**打包**：`package_skill.py` 脚本只要有 Python 和文件系统就能跑。在 Claude.ai 上你也可以运行它，用户可以下载生成的 `.skill` 文件。换句话说，跨环境的可移植性在打包这一步是有保障的——你不必担心用户拿到 .skill 文件之后会遇到环境兼容问题。
+**打包**：`package_skill.py` 脚本只要有 Python 和文件系统就能跑。在 Claude.ai 上你也可以运行它，用户可以下载生成的 `.skill` 文件。
+
+**更新一个已存在的技能**：用户可能让你更新一个已存在的技能，而不是创建新技能。这时：
+- **保留原有的名字。** 注意原技能的目录名和 `name` 字段，原样使用。例如已安装的技能叫 `research-helper`，就输出 `research-helper.skill`（不要写成 `research-helper-v2`）。
+- **先复制到可写入的位置再编辑。** 已安装的技能路径可能是只读的。先复制到 `/tmp/skill-name/`，在那里编辑，再从副本打包。
+- **如果要手动打包，先在 `/tmp/` 里组装好**，然后再复制到输出目录——直接写入输出目录可能因权限失败。
 
 ---
 
 ## Cowork 专用说明
 
-如果你在 Cowork 环境里，主要要知道这几件事。Cowork 与 Claude Code 的能力大体接近，但在浏览器/显示器/服务器进程这几个点上需要绕一下：
+如果你在 Cowork 环境里，主要要知道这几件事：
 
 - 你有子代理，所以主流程（并行启动测试用例、跑基线、打分等等）都能照常工作。（不过如果你遇到严重的超时问题，把测试提示词改成串行执行也是可以的。）
 - 你没有浏览器、也没有显示器，所以在生成 eval 查看器时请使用 `--static <output_path>` 生成一份独立 HTML，而不是启动服务器。然后把这个链接抛出来，用户可以点开在自己浏览器里查看。
-- 出于一些原因，Cowork 这个环境似乎容易让 Claude 在跑完测试后不去生成 eval 查看器——所以再次强调：不管是 Cowork 还是 Claude Code，跑完测试之后你都应当先生成 eval 查看器、让用户先看一遍例子，然后再亲自去改进技能、做更正——而且必须使用 `generate_review.py`（不要自己手写一份花式 HTML）。抱歉这里我要全大写一下：先把 EVAL VIEWER *生成出来*，再去自己评估输出。目的是让人尽快看到结果！把 Claude 自己的评估提前到用户评审之前，是一个常见的反模式——它会让你过早收敛到某个方向，错过用户本来能给出的关键提示。
+- 出于一些原因，Cowork 这个环境似乎容易让 Claude 在跑完测试后不去生成 eval 查看器——所以再次强调：不管是 Cowork 还是 Claude Code，跑完测试之后你都应当先生成 eval 查看器、让用户先看一遍例子，然后再亲自去改进技能、做更正——而且必须使用 `generate_review.py`（不要自己手写一份花式 HTML）。抱歉这里我要全大写一下：先把 EVAL VIEWER *生成出来*，再去自己评估输出。目的是让人尽快看到结果！
 - 反馈机制不同：因为没有在跑的服务器，查看器里的 "Submit All Reviews" 按钮会把 `feedback.json` 作为文件下载。你之后从那个位置去读取它（可能需要先申请访问权限）。
 - 打包能用——`package_skill.py` 只需要 Python 和文件系统。
-- Description 优化（`run_loop.py` / `run_eval.py`）在 Cowork 下应当也没问题，因为它是通过子进程调用 `claude -p`，不是浏览器；但还是请等到技能整体做完、用户也认可后再做这一步。理由是：description 优化是基于现有 description 反复迭代的，如果技能正文还在大改，触发模式也会跟着变化，提前优化基本是白费力气。
+- Description 优化（`run_loop.py` / `run_eval.py`）在 Cowork 下应当也没问题，因为它是通过子进程调用 `claude -p`，不是浏览器；但还是请等到技能整体做完、用户也认可后再做这一步。
+- **更新一个已存在的技能**：用户可能让你更新一个已存在的技能，而不是创建新技能。参照上方 Claude.ai 节里的"更新一个已存在的技能"指引执行。
 
 ---
 
 ## 参考文件
 
-agents/ 目录下是各种专用子代理的指令文件。需要派出对应的子代理时再去读取。把这些子代理指令独立成文件是有意为之——它们不会塞进主 SKILL.md 占用主线程的上下文，只有真要派子代理执行那项任务时才被加载。
+agents/ 目录下是各种专用子代理的指令文件。需要派出对应的子代理时再去读取。
 
 - `agents/grader.md` — 如何对照输出来评估断言
 - `agents/comparator.md` — 如何对两份输出做盲式 A/B 对比
 - `agents/analyzer.md` — 如何分析为什么某一版本胜出
 
-references/ 目录下是额外的文档，作为细节性的参考材料按需查阅：
+references/ 目录下是额外的文档：
 - `references/schemas.md` — evals.json、grading.json 等的 JSON 结构
 
 ---
 
 最后再把核心循环重申一次，以示强调：
 
-- 弄清楚这个技能要解决什么问题、面向哪些用户场景
+- 弄清楚这个技能要解决什么问题
 - 起草或编辑这个技能
 - 让带有这个技能的 Claude 在测试提示词上运行
 - 与用户一道评估输出：
   - 生成 benchmark.json 并运行 `eval-viewer/generate_review.py` 来辅助用户评审
   - 跑一遍定量评估
 - 反复迭代，直到你和用户都满意
-- 把最终的技能打包，并交付给用户；必要时附上一份简短的使用说明
+- 把最终的技能打包，并交付给用户
+
+如果你那边有 TodoList 这种工具，请把这些步骤加进去，免得忘记。如果你在 Cowork 环境，请特别把 "Create evals JSON and run `eval-viewer/generate_review.py` so human can review test cases" 加进 TodoList，确保它真的会被执行。
 
-如果你那边有 TodoList 这种工具，请把这些步骤加进去，免得忘记。如果你在 Cowork 环境，请特别把 "Create evals JSON and run `eval-viewer/generate_review.py` so human can review test cases" 加进 TodoList，确保它真的会被执行。这条容易遗漏的原因之一是：在没有浏览器的环境里，"生成查看器"看起来不像在 Claude Code 里那么显眼，但它正是把决策权交还给用户的关键一步——少了这一步，整个迭代就退化成了 Claude 自言自语。
+祝顺利！
+
+---
 
-祝顺利！愿你做出来的技能可以稳健地服务于成千上万次未来调用。
+*方法论改编自 [anthropics/skills](https://github.com/anthropics/skills)（Apache 2.0）。*

package/template/skills/zh/skill-creator/references/schemas.md

@@ -1,12 +1,12 @@
 # JSON Schemas
 
-This document defines the JSON schemas used by skill-creator.
+本文档定义 skill-creator 使用的各类 JSON schema。
 
 ---
 
 ## evals.json
 
-Defines the evals for a skill. Located at `evals/evals.json` within the skill directory.
+定义某个技能的评估项。位于该技能目录下的 `evals/evals.json`。
 
 ```json
 {
@@ -26,19 +26,19 @@ Defines the evals for a skill. Located at `evals/evals.json` within the skill di
 }
 ```
 
-**Fields:**
-- `skill_name`: Name matching the skill's frontmatter
-- `evals[].id`: Unique integer identifier
-- `evals[].prompt`: The task to execute
-- `evals[].expected_output`: Human-readable description of success
-- `evals[].files`: Optional list of input file paths (relative to skill root)
-- `evals[].expectations`: List of verifiable statements
+**字段：**
+- `skill_name`：与技能 frontmatter 中的 name 一致
+- `evals[].id`：唯一的整数标识
+- `evals[].prompt`：要执行的任务
+- `evals[].expected_output`：以人类可读方式描述的成功标准
+- `evals[].files`：可选的输入文件路径列表（相对于技能根目录）
+- `evals[].expectations`：可被核验的断言列表
 
 ---
 
 ## history.json
 
-Tracks version progression in Improve mode. Located at workspace root.
+跟踪 Improve 模式下的版本演进。位于工作区根目录。
 
 ```json
 {
@@ -71,21 +71,21 @@ Tracks version progression in Improve mode. Located at workspace root.
 }
 ```
 
-**Fields:**
-- `started_at`: ISO timestamp of when improvement started
-- `skill_name`: Name of the skill being improved
-- `current_best`: Version identifier of the best performer
-- `iterations[].version`: Version identifier (v0, v1, ...)
-- `iterations[].parent`: Parent version this was derived from
-- `iterations[].expectation_pass_rate`: Pass rate from grading
-- `iterations[].grading_result`: "baseline", "won", "lost", or "tie"
-- `iterations[].is_current_best`: Whether this is the current best version
+**字段：**
+- `started_at`：改进流程启动时间的 ISO 时间戳
+- `skill_name`：正在改进的技能名
+- `current_best`：当前表现最好的版本标识
+- `iterations[].version`：版本标识（v0、v1、…）
+- `iterations[].parent`：本版本派生自哪个父版本
+- `iterations[].expectation_pass_rate`：评分得出的通过率
+- `iterations[].grading_result`："baseline"、"won"、"lost" 或 "tie"
+- `iterations[].is_current_best`：本版本是否是当前最佳版本
 
 ---
 
 ## grading.json
 
-Output from the grader agent. Located at `<run-dir>/grading.json`.
+由评分智能体输出。位于 `<run-dir>/grading.json`。
 
 ```json
 {
@@ -149,20 +149,20 @@ Output from the grader agent. Located at `<run-dir>/grading.json`.
 }
 ```
 
-**Fields:**
-- `expectations[]`: Graded expectations with evidence
-- `summary`: Aggregate pass/fail counts
-- `execution_metrics`: Tool usage and output size (from executor's metrics.json)
-- `timing`: Wall clock timing (from timing.json)
-- `claims`: Extracted and verified claims from the output
-- `user_notes_summary`: Issues flagged by the executor
-- `eval_feedback`: (optional) Improvement suggestions for the evals, only present when the grader identifies issues worth raising
+**字段：**
+- `expectations[]`：评过分的期望，附证据
+- `summary`：通过/失败的汇总计数
+- `execution_metrics`：工具使用与输出体量（来自 executor 的 metrics.json）
+- `timing`：墙钟时间（来自 timing.json）
+- `claims`：从输出中抽取并核实的论断
+- `user_notes_summary`：executor 标记的问题
+- `eval_feedback`：（可选）针对评估项的改进建议，仅当评分智能体发现值得提出的问题时才出现
 
 ---
 
 ## metrics.json
 
-Output from the executor agent. Located at `<run-dir>/outputs/metrics.json`.
+由执行智能体输出。位于 `<run-dir>/outputs/metrics.json`。
 
 ```json
 {
@@ -183,22 +183,22 @@ Output from the executor agent. Located at `<run-dir>/outputs/metrics.json`.
 }
 ```
 
-**Fields:**
-- `tool_calls`: Count per tool type
-- `total_tool_calls`: Sum of all tool calls
-- `total_steps`: Number of major execution steps
-- `files_created`: List of output files created
-- `errors_encountered`: Number of errors during execution
-- `output_chars`: Total character count of output files
-- `transcript_chars`: Character count of transcript
+**字段：**
+- `tool_calls`：按工具类型计数
+- `total_tool_calls`：所有工具调用之和
+- `total_steps`：主要执行步骤数
+- `files_created`：创建的输出文件列表
+- `errors_encountered`：执行期间的错误数
+- `output_chars`：输出文件的总字符数
+- `transcript_chars`：transcript 的字符数
 
 ---
 
 ## timing.json
 
-Wall clock timing for a run. Located at `<run-dir>/timing.json`.
+一次运行的墙钟计时。位于 `<run-dir>/timing.json`。
 
-**How to capture:** When a subagent task completes, the task notification includes `total_tokens` and `duration_ms`. Save these immediately — they are not persisted anywhere else and cannot be recovered after the fact.
+**如何记录：** 当一个子智能体任务结束时，任务通知中会包含 `total_tokens` 与 `duration_ms`。请立即保存——它们不会持久化到其他地方，事后无法恢复。
 
 ```json
 {
@@ -218,7 +218,7 @@ Wall clock timing for a run. Located at `<run-dir>/timing.json`.
 
 ## benchmark.json
 
-Output from Benchmark mode. Located at `benchmarks/<timestamp>/benchmark.json`.
+Benchmark 模式的输出。位于 `benchmarks/<timestamp>/benchmark.json`。
 
 ```json
 {
@@ -285,30 +285,30 @@ Output from Benchmark mode. Located at `benchmarks/<timestamp>/benchmark.json`.
 }
 ```
 
-**Fields:**
-- `metadata`: Information about the benchmark run
-  - `skill_name`: Name of the skill
-  - `timestamp`: When the benchmark was run
-  - `evals_run`: List of eval names or IDs
-  - `runs_per_configuration`: Number of runs per config (e.g. 3)
-- `runs[]`: Individual run results
-  - `eval_id`: Numeric eval identifier
-  - `eval_name`: Human-readable eval name (used as section header in the viewer)
-  - `configuration`: Must be `"with_skill"` or `"without_skill"` (the viewer uses this exact string for grouping and color coding)
-  - `run_number`: Integer run number (1, 2, 3...)
-  - `result`: Nested object with `pass_rate`, `passed`, `total`, `time_seconds`, `tokens`, `errors`
-- `run_summary`: Statistical aggregates per configuration
-  - `with_skill` / `without_skill`: Each contains `pass_rate`, `time_seconds`, `tokens` objects with `mean` and `stddev` fields
-  - `delta`: Difference strings like `"+0.50"`, `"+13.0"`, `"+1700"`
-- `notes`: Freeform observations from the analyzer
-
-**Important:** The viewer reads these field names exactly. Using `config` instead of `configuration`, or putting `pass_rate` at the top level of a run instead of nested under `result`, will cause the viewer to show empty/zero values. Always reference this schema when generating benchmark.json manually.
+**字段：**
+- `metadata`：本次 benchmark 运行的信息
+  - `skill_name`：技能名
+  - `timestamp`：benchmark 运行的时间
+  - `evals_run`：评估名或 ID 列表
+  - `runs_per_configuration`：每种配置下的运行次数（如 3）
+- `runs[]`：单次运行的结果
+  - `eval_id`：评估的数字标识
+  - `eval_name`：人类可读的评估名（在 viewer 中作为分节标题）
+  - `configuration`：必须为 `"with_skill"` 或 `"without_skill"`（viewer 用该字符串做分组和配色）
+  - `run_number`：整数运行编号（1、2、3…）
+  - `result`：嵌套对象，含 `pass_rate`、`passed`、`total`、`time_seconds`、`tokens`、`errors`
+- `run_summary`：按配置的统计聚合
+  - `with_skill` / `without_skill`：各包含 `pass_rate`、`time_seconds`、`tokens`，每项含 `mean` 与 `stddev`
+  - `delta`：差值字符串，如 `"+0.50"`、`"+13.0"`、`"+1700"`
+- `notes`：分析智能体的自由格式观察
+
+**重要：** viewer 严格按这些字段名读取。把 `config` 写成 `configuration` 之外的形式，或把 `pass_rate` 放在 run 的顶层而非嵌套于 `result` 之下，都会导致 viewer 显示为空或为零值。在手工生成 benchmark.json 时务必参照此 schema。
 
 ---
 
 ## comparison.json
 
-Output from blind comparator. Located at `<grading-dir>/comparison-N.json`.
+由盲比较器输出。位于 `<grading-dir>/comparison-N.json`。
 
 ```json
 {
@@ -383,7 +383,7 @@ Output from blind comparator. Located at `<grading-dir>/comparison-N.json`.
 
 ## analysis.json
 
-Output from post-hoc analyzer. Located at `<grading-dir>/analysis.json`.
+由事后分析器输出。位于 `<grading-dir>/analysis.json`。
 
 ```json
 {