skillz

skillz

添加、改进、审计、拆分并自动改进技能。 改进和审计也接受 Agent 定义。 该产品是一个可预测的定义：每次运行、每种运行框架都遵循相同流程。 每个审视角度都会针对每一行提出一个问题：这能让运行更可预测，还是只是沉积物？

模式是技能名称后的第一个词。 Aliases 列列出选择同一模式的名称。 每种模式都必须指定目标。 如果缺少模式，请询问模式。 如果该模式需要目标但未提供，请询问目标。

模式

模式	别名	目标	分析	写入	产物
add <name>	无	新技能名称	否	创建 skills/<name>/	通过评估标准的已注册技能
improve <path>	optimize、tighten	SKILL.md 或 Agent 文件	是，除非复用当前审计结果	分析缓存；批准后写入目标	已批准的修复项 + 剩余发现
audit <path>	无	SKILL.md 或 Agent 文件	是	仅分析缓存；绝不写入目标	校准后的报告
wedge <path>	无	SKILL.md	否	目标技能：每个选定的 CLI、其交付文件、调用位置，以及任何依赖项写入	拆分说明，然后为每个选定候选项提供一个 CLI；拆分时各自置于独立目录，或说明原因
autoimprove <path>	experiment	技能目录；不接受合约或清单	用户批准的用例；存在分析数据时使用 Agent 起草的会话用例	隔离的运行目录	留出集门控判定和私有候选补丁

audit 绝不修改目标。audit 和 improve 的 Usage 流程会运行 scripts/agent-session-analytics.pyz ingest，以创建或刷新分析缓存。 详情见 references/analytics-ceremony.md。跳过 Usage 和原始日志回退流程都不会写入缓存。

对于 autoimprove，请阅读 references/experiments.md。遵循其中的工作流，而不是共享审计协议。 在写入或检查 evals/evals.json、evals/journeys.json 或 evals/autoimprove.json 之前，请阅读 references/eval-formats.md。 由 Agent 起草用例。用户无需提供合约或用例清单。 运行 scripts/skillz-experiment.pyz run，回答每个编码停止项，然后运行 export。 最多提出三个问题：运行框架和模型、用例审批、预算审批。 报告 runner、export 和 improvement 的声明，并分别附上状态和证据。仅当 claims.apply 为 true 时才应用胜出方案。 用户选择 claude 适配器或自定义命令检查时，也请阅读 references/experiment-harness.md。 对于 Gemini CLI、Copilot CLI、Cursor CLI、OpenCode 或 Pi，也请阅读 references/harness-recipes.md。 使用已安装的 scripts/skillz-experiment.pyz。不要要求检出源代码。

共享协议

1. 阅读并分类

阅读目标。只有当运行时符合所述触发条件，才阅读链接的参考资料。 完整的软件包审计可以明确要求阅读目标软件包中的每个文件。 对于技能目录，在应用评分标准前运行 python3 <this-skill-directory>/scripts/skillz-experiment.pyz audit-facts <skill-directory>。 还要运行 python3 -I <this-skill-directory>/scripts/inspect-skill.pyz <target>，获取正文事实。 将两份 JSON 输出都作为客观的软件包事实，而非适用性评分。Agent 文件不属于任何软件包，因此跳过 audit-facts。 阅读 references/experiments.md § Audit facts contract，了解检查 ID 和状态。 报告辅助工具错误，不要将其视为审计成功。 将其分类为 Agent（tools: / disallowedTools: 或 agents/registry.yaml 条目）或 技能（name: + description:）。 对于技能，运行 git ls-files -z -co --exclude-standard <skill-dir> | LC_ALL=C sort -z | xargs -0 git hash-object | git hash-object --stdin。 其输出即为内容 ID。它涵盖软件包中的每个文件，因此旁置文件或参考资料的编辑也会改变它。 对于 Agent 文件，运行 git hash-object <target>。其输出即为内容 ID。 如果命令失败，内容 ID 为 unavailable。 报告正文大小为 ~N tok，并以 5k 为预算。对于技能，复制 body.token-estimate 检查项中的数值。对于 Agent 文件，在 frontmatter 区块后按每 4 字节计 1 个 token。 列出该定义所涉及的部署目标（参阅 references/harness-layout.md § Layout）。

2. 评分标准

为每个维度评分。 每一行都列出原则、其所捕捉的失败模式，以及可核查的测试。 当某项发现需要扩展说明时，阅读 references/anti-patterns.md。

维度	原则 → 可发现的问题	检查方式
可预测性	固定协议，完成条件可核验 → «过早完成»	每个步骤都以 Agent 可核验的完成条件收尾。
调用	description = 触发条件，置于前面，使用第三人称 → «工作流摘要»、«摘要描述»	触发短语 + "Do NOT use for"；不包含内部工作流；技能的长度取决于 description.length，Agent 文件需手动保持在 ≤1024 个字符；第一句话包含触发条件。references/description-optimization.md。
可移植性	规范核心 frontmatter 加上增补的 Claude 字段；仅用户级策略适用于所有宿主 → «仅适用于 Claude 的假设»、«缺少 sidecar»、«依赖 $ARGUMENTS»	引用 audit-facts 中未通过的检查，涉及键、sidecar 配对，以及参数、技能目录或文件提及语法。手动判断：参数从技能名称之后的文本中解析；技能通过 /name 交叉引用；分发和 GitHub 操作需先说明约定，再使用宿主语法。完整矩阵：references/harness-layout.md。
信息层级	仅披露部分运行会跳过的内容；正文 ≤5k tok；引用仅嵌套一层，每项都注明读取触发条件 → «内容膨胀»、«无触发条件的拆分»、«强制加载 @file»	引用 audit-facts 中未通过的检查，涉及令牌预算、嵌套引用、孤立内容和缺失的读取触发条件。手动判断：仅当运行会根据该段内容分支，且 ## References 条目注明触发条件时，迁移才算有效。references/progressive-disclosure.md。
措辞（ASD-STE100）	主动语态、现在时、每句一条指令、句子简短 → «被动语态»、«多指令句»、«长句»	引用 inspect-skill.pyz 的 long_sentences 事实（超过 25 个单词的句子）。仅对程序性步骤引用 advisory_sentences（21 至 25 个单词）。将被动语态和多指令句列为发现项。
开头用词	一个预训练词胜过重复表述的三项内容 → «重复»、«无效的弱词»	合并重复表述；强化弱词（be thorough → relentless）。
精简	单一事实来源；删除无效内容 → «陈旧堆积»	同一含义不在两处重复；不保留模型默认会遵循的冗余句子。删除整句。
确定性卸载	将固定计算作为打包命令运行，而非重新生成文字 → «内联脚本»	不让模型在每次运行时编写或重新推导相同的解析、计数、筛选、排序或投影步骤；scripts.invocation-line 检查调用行；wedge.own-targets 和 wedge.foreign-binary 检查 wedge 状态；判断每个打包脚本是否有输出约定。使用 references/offload.md 修复。
工具范围	只读／限定写入范围／用途明确；有宿主强制机制时优先使用 → «仅靠措辞约束»	Claude 技能使用 disallowed-tools 移除当前轮次可用的工具。allowed-tools 授予权限而不弹出提示；它不是拒绝列表。Claude Agent 使用 disallowedTools。报告各模式的实际强制机制，并将仅靠措辞的限制标为降级。不要为 improve 禁用写入。
上下文与分叉	输出超过约 500 行或只需摘要时分叉 → «单体式输出»	分叉与规模匹配；存在收尾信号；model-policy.* 检查涵盖 model: + effort:。
提示词质量	正向措辞、解释原因而非仅说明要求、一个有力示例、「What this never does」→ «过度使用否定表达»、«规则没有理由»	判断任务使用脚手架，而非总是／从不之类的表述。references/decision-frameworks.md。
置信度校准	判断型 Agent 标注置信度 × 严重性 → «未经校准的判断»	<certain> / <speculative> / <don't know>；绝不输出不知道。
输出格式	摘要置前，用表格列出发现项，明确标示无问题与存在问题 → «没有输出格式»	定义格式；区分摘要与详情。
用法 (审计、改进)	声明与实际相符 → «声明与实际不符»、«衰退»	声明的工具就是实际使用的工具；错误率接近基线；用量未下降。

3. 校准

为每项发现标注严重程度 × 置信度。 核心规则见 references/calibration.md；默认值如下：

• 按评估维度划分的严重程度 — 可预测性、调用、可移植性、工具范围、校准 → high；信息层级、上下文与分支、精简 → high/medium；引导词、行文、确定性卸载、输出格式、用法 → medium。
• 置信度 — 有引用行和具体故障、正确示范的参考，或分析数据 → <certain>；可核查但未经验证的观察 → <speculative>；误读 → <don't know>，删除。
• 重新推导 — 重新阅读目标文件，不看第一遍结果，重新推导每项 <speculative> 发现。若无法复现，则删除。
• 按严重程度排序，然后将 <certain> 排在前面。

行文检查

add 的第 6 步和 improve 的第 5 步会运行此检查。

1. 对 SKILL.md 或 Agent 文件运行 python3 -I <this-skill-directory>/scripts/inspect-skill.pyz <target file>。
2. 重写 long_sentences 中的每个句子（超过 25 个单词）。 对每条 advisory_sentences 项（21 至 25 个单词），如果它是操作步骤，也要重写。
3. 对于已更改的参考文件，手动应用这两项限制：25 个单词；操作步骤为 20 个单词。

辅助工具会拒绝没有 frontmatter 的文件，因此无法检查参考文件。

模式：add

1. 确认名称：使用 kebab-case，不超过 64 个字符，目录名称与 name: 一致，并且在 skills/、~/.claude/skills、~/.agents/skills 中没有重名。
2. 从参数中收集信息，或询问以下内容：一句话用途、至少 5 个触发短语、反触发条件、调用策略和 harness 集合。 调用策略为由模型调用或仅限用户调用。
3. 根据 references/harness-layout.md § Template 编写技能。 创建时正文不超过 2k tok。 仅当某个区块会被部分运行跳过时，才创建参考文件。 如果技能仅限用户调用，则添加 agents/openai.yaml。 仅当技能由模型调用时，才设置 model + effort。
4. 根据 references/harness-layout.md § Evals 编写 evals/evals.json。 每个触发短语添加一个触发用例，每个反触发条件添加一个近似误触用例。 根据用途和流程至少拟定三个任务用例。 为每个任务用例添加 assertions，以便评分器能够检查输出。
5. 在技能所在仓库的索引中注册该技能（references/harness-layout.md § Registration）。 仓库本地技能不得加入任何全局列表；按 references/harness-layout.md § Repo-local skills 放置。
6. 报告模式已完成前，先对 SKILL.md 和每个已更改的参考文件运行行文检查。
7. 对新文件运行一次 improve。跳过 Usage，因为新技能尚无会话。 然后运行仓库的部署步骤（如果存在）。 部署步骤示例包括 dotfiles 同步、npx skills add，或复制到 harness 技能目录。

完成条件：文件存在且仓库索引列出了该文件，或每个仓库本地宿主路径都能解析。 evals/evals.json 为每个触发短语和反触发条件各包含一个用例，另有至少三个任务用例。 如果存在部署步骤，则该步骤以 0 退出。Invocation 评估维度通过。 检查器报告的 long_sentences 列表为空。

模式：改进

1. 获取目标的最新审查结果。 如果本次对话中已有审查报告，且其目标和内容 ID 匹配，则复用该报告。注明所复用的报告。 unavailable 内容 ID 永不匹配。 否则，执行 audit 步骤 1-3。缺少 Usage 时，说明原因。
2. 在首次编辑前展示发现项表格，每项发现提供一条建议。 对于严重程度为中或更高且不改变协议语义的 <certain> 发现，建议 apply。 对于 Deterministic 卸载发现，建议 offload 或 decline。卸载会改变协议语义，因此需要明确批准。 对于其他所有发现，建议 apply 或 decline。说明理由。
3. 提出一个涵盖所有已列出发现项的审批问题。 应用已批准的发现项。使用 references/offload.md 实现每项已批准的卸载。 将已拒绝的发现项记录为残留项。 委派运行会将发现项返回给父级，由父级提出审批问题。 PR 正文或报告不构成批准。
4. 保持目标的语气和协议语义。仅针对已批准的项目进行更改。
5. 在报告模式已完成之前，对目标文件和每个已更改的引用文件运行 prose 检查。
6. 重新测量正文。报告前后 token 数和残留发现项。
7. 如果目标位于 skills/ 或 agents/ 目录树下，且会由同步流程分发，则运行仓库的部署步骤。 确认部署副本与源文件一致；同名的 vendored skill 会覆盖本地版本（harness-layout.md § Layout）。

完成标准：报告注明所复用的审查，或说明审查是最新的。 用户在首次编辑前能看到所有已列出的发现项。用户会对审批问题涵盖的每项发现作出批准或拒绝。 本次运行会应用所有已批准的发现项。 正文不超过 5k tok。检查器报告的 long_sentences 列表为空。仓库质量门禁以 0 退出。

模式：审查

1. 执行共享协议 §1「读取并分类」，以确定 target_kind。
2. 根据该类型运行 references/analytics-ceremony.md。如果缺少 DuckDB，则改为阅读 references/raw-log-fallback.md 和 references/harness-coverage.md。回退流程的步骤 1 会提出一个问题：安装 DuckDB、批准抽样扫描，或跳过 Usage。未经同意，绝不运行扫描。
3. 使用 Usage 摘要运行共享协议 §2-3。
4. 输出下方的报告。不要修改目标。除分析缓存外，不写入任何内容。
5. 以 Run /skillz improve <path> to apply. 结束。在本次对话中，只要内容 ID 匹配，improve 就会复用此报告。

完成标准：报告列出每项已发现的问题并附有引用行号，同时注明低于门槛的问题数量。

模式：wedge

找出目标技能中的固定工作，并将其移入 CLI。 遵循 references/offload.md；步骤为 Find、Contract、Implement、Deliver 和 Wire。

1. 阅读目标及其 scripts/。仅评估 Deterministic offload 维度。 对于 Agent 文件，报告 wedge 只会修改技能，然后停止。
2. 对每个候选项运行 Find 和 Contract。引用每个候选项所在的行。 按每次运行重复该工作的频率排序；频率相同时，按目标行号升序排序。 如果没有候选项，报告 No offload candidates 并停止。
3. 输出以下简报。 询问用户要实现哪些候选项，并给出你的建议。 在同一个问题中，询问用户是否拒绝使用 fromargs 或进行 wedge。 在问题中列出每项依赖项写入操作。
4. 对每个选定的候选项运行 Implement、Deliver 和 Wire。 Implement 之前阅读 references/fromargs.md，除非用户拒绝使用 fromargs。 对 CLI 进行 wedge 之前阅读 references/wedge-packaging.md。
5. 对目标 SKILL.md 运行 prose 检查。然后运行仓库的质量门禁。
6. 当同步会分发目标时，运行仓库的部署步骤，正如 improve 步骤 7 所做的那样。 确认部署后的副本与源文件一致。

完成标准：每个候选项都引用了行号，并包含全部七个契约字段。 每个选定的 CLI 都通过其调用行对应的契约测试。 每个未进行 wedge 的 CLI 都说明了原因。

## skillz wedge: <name>

| # | Step (line) | Transformation | Command | Delivery | Stays in prose |
|---|---|---|---|---|---|

### Candidate <n>: <command>
**Inputs** · **Output** · **Ordering** · **Empty** · **Errors** · **Side effects** · **Caller line**

报告

## skillz <mode>: <name>

- Type: agent | skill · Invocation: model | user-only · Tools: <N allowed, N disallowed> · Body: ~N tok (before → after for improve)
- Harnesses reached: <list> · Findings: N surfaced, N below the bar
- Target: <path> · Content id: <id | unavailable> · Usage: included | omitted (<reason>) · Audit: fresh | reused <content id> (improve only)

| # | Severity | Confidence | Lens | Issue (line) | Fix | Recommendation (apply / decline / `/skillz wedge`) | Decision (approved / declined / pending / residual; improve only) |
|---|---|---|---|---|---|---|---|

### Detail (per surfaced finding)
**What** · **Why** (the principle) · **How** (exact section) · **Reference** (a definition that does it right)

### Recommended hooks
Only for a rule that must hold every time; pick from `references/hooks-catalog.md`. Omit when none.

### Below the bar
N findings were `<don't know>` or trivial (not shown).

此技能绝不做的事

• audit 绝不修改目标，只写入分析缓存。
• wedge 只写入用户选定的候选项。
• improve 绝不在用户回答批准问题之前编辑内容，也绝不未经批准更改协议语义。
• add 绝不注册描述未通过 Invocation 维度的技能。
• 绝不显示 <don't know>。
• 绝不为自身破例；针对 skillz 的发现也会像其他发现一样记录。

注意事项

• 对简单技能提出泛泛的发现：每项发现都必须引用行号或命名的模式。
• 当宿主默认设置已限制工具列表时，过度关注缺少 disallowedTools。
• 时间紧迫时，最先被跳过的是 <speculative> 重新推导步骤，但它也最能发现误报。
• 单独使用 disable-model-invocation 仍允许 Codex 自动调用；解决办法是 sidecar，而非增加更多说明文字。
• Hook 用于必须始终成立的规则，而非每项发现都要配一个 hook。

参考资料

按需阅读：

• references/harness-layout.md — Portability 检查触发，或执行 add（全局或仓库本地）时；包含 frontmatter 矩阵、规则、模板、评估、sidecar 和来源。
• references/analytics-ceremony.md — 执行 audit，或在没有可复用审计的情况下执行 improve 时；使用 scripts/agent-session-analytics.pyz 尽力进行按工具包分析。
• references/raw-log-fallback.md — 缺少 DuckDB 时；用户可安装它、选择进行抽样只读 Usage 扫描，或跳过。
• references/anti-patterns.md — 发现项需要展开说明其失败模式时。
• references/offload.md — 执行 wedge，或 improve 实施了获批的卸载时；包含通用流程。
• references/fromargs.md — 卸载操作会写入 fromargs CLI 时。
• references/wedge-packaging.md — 卸载操作将 CLI 封装为 wedge 之前；构建器为 scripts/wedge.pyz。
• assets/records.py、assets/wedge.toml — 卸载操作复制的 CLI 和清单模板。
• evals/evals.json — 压力测试场景；更改卸载流程时请使用。
• references/progressive-disclosure.md — Information hierarchy 检查触发时。
• references/description-optimization.md — Invocation 检查触发时。
• references/decision-frameworks.md — Prompt quality 标记出判断任务中的僵化规则时。
• references/hooks-catalog.md — 发现项需要 100% 强制执行，或 Invocation 建议使用强制评估 hook（§1）时。
• references/skill-usage.md、references/agent-orchestration.md、references/drift-regression.md — 分析工具包。进行分析流程时，将每个工具包路径和目标类型传递给对应的工具包上下文。只有在宿主没有子 Agent 时才阅读工具包。
• scripts/agent-session-analytics.pyz — 分析 CLI：ingest、db-path、sql 和 schema。
• references/canonical-schema.md — 工具包输入 schema；编写或检查工具包 SQL 时阅读。
• references/query-conventions.md — 工具包输入 conventions；编写工具包或运行其查询时阅读。
• references/harness-coverage.md — 工具包输入 coverage；进行跨 harness 比较以及使用原始日志回退方案时阅读。
• 在分析流程中，将这三个路径作为 schema、conventions 和 coverage 传递给每个工具包上下文。
• references/calibration.md — 标记发现项的严重性和置信度时；包含置信度 × 严重性核。
• references/experiments.md — 执行 autoimprove，或执行需要检查 ID 的 audit 时；包含运行流程、案例草案、门禁判定、导出、可选契约、评分器、隔离和辅助程序契约。
• references/eval-formats.md — 作者编写的评估文件；包含字段、架构、$schema、最低要求和 validate。
• references/experiment-harness.md — 用户选择 claude 适配器，或检查自定义命令或角色文件时。
• references/harness-recipes.md — 用户希望通过 Gemini CLI、Copilot CLI、Cursor CLI、OpenCode 或 Pi 运行实验时。