skill-authoring · git:20260728.674d592 · 2026-07-28 · sha256 03cc6d3f47fbebe4
skill-authoring git:20260728.674d592A
Immutable. This exact content is served forever at /api/v1/blob/03cc6d3f47fbebe4.
--- name: skill-authoring description: Codify the Iron Law, Red Flags, and Rationalization-table template that easy-cheese skills follow, plus the CSO description rule and size-budget checklist for authoring or revising a skill. Use when writing a new skill or SKILL.md, adding a discipline section, or reviewing an existing skill against easy-cheese's authoring conventions. --- # Skill Authoring — easy-cheese conventions 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. --- ## Description rule (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. --- ## 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. --- ## 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. ### 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. --- ## 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. --- ## Pressure-test-first authoring gate **Iron Law: no skill ships without a failing-baseline subagent run first.** Before writing a new skill body: 1. Construct a representative pressure scenario — a prompt that describes a task the skill is meant to improve. 2. Run a subagent on that scenario *without* the skill active. Capture the output as the baseline. 3. Identify the specific failure: what did the subagent do wrong, skip, or misframe? 4. Write the skill body to address that specific failure. 5. 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) 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.