skill-authoring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Authoring — easy-cheese conventions

技能创作 — easy-cheese 规范

This document codifies the skill-authoring rules for easy-cheese, drawn from obra/superpowers (CSO principle, Iron Law template, pressure-test gate) and Matt Pocock's skills repo (size budget, authoring checklist). It is the canonical reference for anyone adding or revising a skill.

本文档整理了easy-cheese的技能创作规则，这些规则源自obra/superpowers（CSO原则、铁律模板、压力测试关卡）和Matt Pocock的技能仓库（规模预算、创作检查清单）。这是所有添加或修订技能人员的权威参考。

Description rule (CSO)

描述规则（CSO）

The description is the only thing the harness shows the model when choosing a skill. Optimize it for triggering, not explanation.

The rule: sentence 1 = capability; sentence 2 = "Use when [triggering conditions]". No workflow summary, no pipeline-position prose, no feature list.

Rationale: a description that summarizes the skill's workflow creates a shortcut the model takes instead of reading the SKILL.md body. The skill then silently degrades to its own one-line description.

Constraints:

Maximum 1024 characters (Codex rejects longer descriptions).
Third-person, present tense.
Triggering conditions name concrete phrases the user might say.

Test: strip the description and ask: could a model choose this skill over all others based on these words alone? If not, the triggers are missing.

描述是工具在选择技能时展示给模型的唯一内容。优化描述以触发模型选择，而非解释技能。

规则： 第一句 = 能力；第二句 = "适用于[触发场景]"。禁止包含工作流摘要、流程定位说明或功能列表。

理由：总结技能工作流的描述会让模型走捷径，而不去阅读SKILL.md正文。此时技能会悄然退化到仅依赖自身的一行描述。

约束条件：

最多1024个字符（Codex会拒绝更长的描述）。
使用第三人称、现在时态。
触发场景需明确用户可能说出的具体表述。

测试方法： 删除描述后提问：仅根据这些文字，模型能否在所有技能中选中该技能？如果不能，说明缺少触发条件。

Size budget

规模预算

Keep SKILL.md bodies lean. The goal is a body a model can read in one pass without losing the thread.

The budget: 3,600 estimated tokens for the SKILL.md body (frontmatter excluded). At this repo's measured prose density that's roughly 150 lines, but tokens are the gated unit, not lines — line count misleads on dense prose: all 16 skills in this repo pass Anthropic's 500-line rule, while 8 exceed our 3,600-token budget on the same bodies.

Enforcement: CI runs this as a shrink-only ratchet —

.github/scripts/validate_skills.py

, baselines recorded in

.github/skill-budgets.json

, regenerated via

just update-skill-budgets

. A skill already over budget when the ratchet was introduced is grandfathered at its recorded value and may only shrink from there; a skill at or under budget must stay under 3,600.

Anthropic's published Level-2 figures are 500 lines / under 5k tokens. easy-cheese deliberately sits tighter than that ceiling.

Practical budget:

Push satellite detail — step-by-step sub-protocols, reference tables, prompt templates, large examples — into named
```
references/*.md
```
files. The SKILL.md body points to them; it does not duplicate them.
The
```
references/
```
dir is the right home for: long rationalization tables, output format templates, detailed sub-protocol steps, graph conventions.
Splitting only helps if SKILL.md says when to read the reference file. Reference files load only on an explicit link from the body — moving prose into
```
references/
```
without a pointer just relocates the tokens off the visible budget rather than deferring them from the model's read.

Smell test: if the SKILL.md body has grown to the point where the Flow section is buried below a long Inputs section and three flag tables, it is time to factor.

Provenance: the budget originated as an adaptation of Matt Pocock's <100-line cap for his skills repo, and has since been restated in tokens against this repo's own measured prose density.

保持SKILL.md正文简洁。目标是让模型能一次性读完正文而不丢失主线。

预算：SKILL.md正文（不含前置元数据）最多3600个预估tokens。按照本仓库的实际文本密度，这大约相当于150行，但tokens是限制单位，而非行数——行数无法准确反映文本密度：本仓库的16个技能都符合Anthropic的500行规则，但其中8个技能的正文tokens数超过了我们设定的3600预算。

执行方式： CI会将此作为仅允许缩减的机制——通过

.github/scripts/validate_skills.py

执行，基准值记录在

.github/skill-budgets.json

中，可通过

just update-skill-budgets

重新生成。机制引入时已超预算的技能将保留其记录的基准值，且只能从此值开始缩减；处于或低于预算的技能必须保持在3600tokens以下。

Anthropic公布的Level-2标准是500行/低于5000个tokens。easy-cheese刻意设定了比该上限更严格的标准。

实用预算策略：

将辅助细节——分步子流程、参考表格、提示模板、大型示例——移至命名为
```
references/*.md
```
的文件中。SKILL.md正文只需指向这些文件，无需重复内容。
```
references/
```
目录适合存放：长篇合理化表格、输出格式模板、详细子流程步骤、图表规范。
拆分内容仅在SKILL.md说明何时阅读参考文件时才有用。参考文件仅在正文有明确链接时才会加载——如果将文本移至
```
references/
```
但未添加指向它的链接，只是将tokens从可见预算中转移，而非让模型延迟读取这些内容。

嗅探测试： 如果SKILL.md正文已膨胀到“流程”部分被冗长的“输入”部分和三个标志表格压在下方，那么是时候拆分内容了。

来源：该预算最初改编自Matt Pocock技能仓库的<100行限制，之后根据本仓库的实际文本密度重新表述为tokens限制。

Iron Law / Red Flags / Rationalization-table template

铁律 / 危险信号 / 合理化表格模板

Discipline skills (skills that enforce a process, not just explain a technique) follow this three-part structure. Apply it in a

## Discipline

section in the SKILL.md body, or in a

references/<skill>-discipline.md

satellite file when the body is already at budget.

规范类技能（用于执行流程而非仅解释技术的技能）需遵循此三部分结构。可将其应用于SKILL.md正文的

## 规范

章节，或当正文已达预算时，放在

references/<skill>-discipline.md

附属文件中。

Iron Law

铁律

One sentence. States the gate that must never be skipped. The Iron Law is descriptive, not aspirational: it names what the skill will refuse to do without.

Example shape:

Iron Law: No [output] without [prerequisite step] first.

一句话。定义绝不能跳过的关卡。铁律是描述性的，而非理想化的：它明确了技能在缺少什么条件时会拒绝执行任务。

示例格式：

铁律： 未完成[前置步骤]，不得生成[输出]。

Red Flags

危险信号

A short list of signals that the Iron Law is about to be violated. These are the observable pre-rationalizations — the moment before a step gets skipped.

Example shape:

Red Flags — stop if you notice these:

"The tests will obviously pass after this change."

"I'll add the test in the next commit."

[skill-specific patterns]

列出表明铁律即将被违反的信号。这些是可观察到的合理化前兆——即步骤即将被跳过的时刻。

示例格式：

危险信号 —— 若发现以下情况请停止：

“此更改后测试显然会通过。”

“我会在下一次提交中添加测试。”

[技能特定模式]

Rationalization table

合理化表格

A table enumerating the excuses an agent uses to skip the Iron Law step, with an explicit rebuttal for each. The table is adversarial by design: it assumes the model will reach for a rationalization under pressure.

Rationalization	Why it fails	Required action
"The change is obvious, tests would just mirror the code."	A test that mirrors code catches regressions; that is its job.	Write the test.
[skill-specific row]	[rebuttal]	[required action]

Keep the table to the rationalizations actually observed in practice (5-10 rows maximum). An exhaustive list defeats the purpose.

表格列出代理用来跳过铁律步骤的借口，并为每个借口提供明确反驳。表格设计为对抗性：假设模型在压力下会寻找合理化理由。

合理化理由	为何不成立	要求操作
“更改很明显，测试只是重复代码而已。”	重复代码的测试能捕获回归问题，这正是它的作用。	编写测试。
[技能特定行]	[反驳理由]	[要求操作]

表格仅保留实际观察到的合理化理由（最多5-10行）。详尽列表会违背初衷。

Authoring review checklist

创作审核检查清单

Before a skill ships, verify:

Triggers present. The description names concrete phrases the user might say (not capability prose).
No time-sensitive information. Skill bodies must not embed version numbers, dated pricing, or API endpoints that will rot. Point to docs instead.
Concrete examples. At least one worked example exists — either inline or in a
```
references/
```
file.
References one level deep. The SKILL.md body points to
```
references/*.md
```
files; those files do not markdown-link further into their own sub-references. A partial
```
head
```
-style read of a reference file would silently miss the tail of a hidden second hop. A link to a reference file that is itself linked from a SKILL.md is a lateral citation, not a second hop, and passes.
Discipline skills have the Iron Law section. Any skill that enforces a gate or a loop carries the three-part template above.

Dual-listed. The skill's directory appears in the

.claude-plugin/plugin.json

skills

array. The CI check

tests/python/test_plugin_manifest.py::test_claude_plugin_manifest_matches_top_level_skills

enforces this.

技能发布前，请验证：

包含触发条件。描述明确了用户可能说出的具体表述（而非能力说明）。
无时效性信息。技能正文不得嵌入版本号、过期定价或会失效的API端点。应指向文档链接。
包含具体示例。至少有一个实际示例——可内嵌于正文或放在
```
references/
```
文件中。
引用仅一层深度。SKILL.md正文指向
```
references/*.md
```
文件；这些文件不得再通过markdown链接指向自身的子引用。对引用文件进行部分
```
head
```
式读取会遗漏隐藏的二次跳转内容。从SKILL.md链接到的引用文件再链接到其他文件属于横向引用，而非二次跳转，符合要求。
规范类技能包含铁律章节。任何执行关卡或循环的技能都需包含上述三部分模板。

双重列示。技能目录需出现在

.claude-plugin/plugin.json

的

skills

数组中。CI检查

tests/python/test_plugin_manifest.py::test_claude_plugin_manifest_matches_top_level_skills

会强制执行此要求。

Pressure-test-first authoring gate

压力测试优先的创作关卡

Iron Law: no skill ships without a failing-baseline subagent run first.

Before writing a new skill body:

Construct a representative pressure scenario — a prompt that describes a task the skill is meant to improve.
Run a subagent on that scenario without the skill active. Capture the output as the baseline.
Identify the specific failure: what did the subagent do wrong, skip, or misframe?
Write the skill body to address that specific failure.
Re-run the subagent with the skill active and confirm the failure is corrected.

A skill whose body was never tested against a failing baseline may fix a problem the model does not actually have, or it may describe a workflow the model already follows without being told.

铁律：未通过失败基准子代理运行的技能不得发布。

编写新技能正文前：

构建具有代表性的压力场景——一个描述技能旨在改进的任务的提示词。
在未激活技能的情况下，让子代理运行该场景。捕获输出作为基准。
明确具体故障：子代理做错了什么、跳过了什么或误解了什么？
编写技能正文以解决该具体故障。
激活技能后重新运行子代理，确认故障已修复。

若技能正文从未针对失败基准进行测试，它可能解决的是模型实际不存在的问题，或者描述的是模型无需告知就已遵循的工作流。

disable-model-invocation

frontmatter (candidate — not yet applied)

disable-model-invocation

前置元数据（候选功能——尚未应用）

Matt Pocock's skills repo uses

disable-model-invocation: true

in the frontmatter of pure-prompt skills (skills that execute immediately without re-prompting the model). The Claude Code frontmatter validator (

.github/scripts/validate_skills.py

) already allows this key.

Status: candidate-pending-harness-verification. Do not apply to any easy-cheese skill until the harness behavior is confirmed: what does the harness do when this key is set, and does it match the intended "execute immediately" semantics? Document the verification result here before applying.

Matt Pocock的技能仓库在纯提示词技能（无需重新提示模型即可立即执行的技能）的前置元数据中使用

disable-model-invocation: true

。Claude Code前置元数据验证器（

.github/scripts/validate_skills.py

）已支持此键。

状态：候选功能，待工具验证。 在确认工具行为之前，请勿将其应用于任何easy-cheese技能：设置此键后工具会如何处理？是否符合预期的“立即执行”语义？请在此处记录验证结果后再应用。