Skill Authoring

---
name: skill-authoring
description: Codify the discipline-section guidance, the CSO description rule, and the size-budget checklist that easy-cheese skills follow when 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, 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.