skill-authoring

Skill Authoring — easy-cheese conventions

This document codifies the skill-authoring rules for easy-cheese, drawn from obra/superpowers (CSO principle, 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.

---

Discipline sections

Discipline skills (skills that enforce a process, not just explain a technique) state their rule 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.

Keep the section short. State the rule in one sentence, list the observable signals that the rule is about to be broken, and name the required action. Add a rebuttal table only for rationalizations observed in practice.

---

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 sections are short. A skill that enforces a gate or a loop states the rule, the signals that it is about to be broken, and the required action, in a few lines.
• 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

Rule: 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.