{"slug":"skill-authoring-3","title":"skill-authoring","summary":"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 exi","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-10T16:33:18.087366Z","repo":{"url":"https://github.com/paulnsorensen/easy-cheese","stars":18,"forks":1,"license":"MIT","updatedAt":"2026-09-20T13:17:43Z"},"bodyHtml":"<hr>\n<h2>name: skill-authoring\ndescription: 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.</h2>\n<h1>Skill Authoring — easy-cheese conventions</h1>\n<p>This document codifies the skill-authoring rules for easy-cheese, drawn from\nobra/superpowers (CSO principle, Iron Law template, pressure-test gate) and\nMatt Pocock's skills repo (size budget, authoring checklist). It is the\ncanonical reference for anyone adding or revising a skill.</p>\n<hr>\n<h2>Description rule (CSO)</h2>\n<p>The description is the <strong>only thing the harness shows the model when choosing\na skill</strong>. Optimize it for triggering, not explanation.</p>\n<p><strong>The rule:</strong> sentence 1 = capability; sentence 2 = \"Use when [triggering\nconditions]\". No workflow summary, no pipeline-position prose, no feature list.</p>\n<p>Rationale: a description that summarizes the skill's workflow creates a\nshortcut the model takes <em>instead of reading the SKILL.md body</em>. The skill\nthen silently degrades to its own one-line description.</p>\n<p><strong>Constraints:</strong></p>\n<ul>\n<li>Maximum 1024 characters (Codex rejects longer descriptions).</li>\n<li>Third-person, present tense.</li>\n<li>Triggering conditions name concrete phrases the user might say.</li>\n</ul>\n<p><strong>Test:</strong> strip the description and ask: could a model choose <em>this</em> skill over\nall others based on these words alone? If not, the triggers are missing.</p>\n<hr>\n<h2>Size budget</h2>\n<p>Keep SKILL.md bodies lean. The goal is a body a model can read in one pass\nwithout losing the thread.</p>\n<p><strong>The budget: 3,600 estimated tokens</strong> for the SKILL.md body (frontmatter\nexcluded). At this repo's measured prose density that's roughly 150 lines,\nbut tokens are the gated unit, not lines — line count misleads on dense\nprose: all 16 skills in this repo pass Anthropic's 500-line rule, while 8\nexceed our 3,600-token budget on the same bodies.</p>\n<p><strong>Enforcement:</strong> CI runs this as a shrink-only ratchet —\n<code>.github/scripts/validate_skills.py</code>, baselines recorded in\n<code>.github/skill-budgets.json</code>, regenerated via <code>just update-skill-budgets</code>.\nA skill already over budget when the ratchet was introduced is grandfathered\nat its recorded value and may only shrink from there; a skill at or under\nbudget must stay under 3,600.</p>\n<p>Anthropic's published Level-2 figures are 500 lines / under 5k tokens.\neasy-cheese deliberately sits tighter than that ceiling.</p>\n<p><strong>Practical budget:</strong></p>\n<ul>\n<li>Push satellite detail — step-by-step sub-protocols, reference tables,\nprompt templates, large examples — into named <code>references/*.md</code> files.\nThe SKILL.md body points to them; it does not duplicate them.</li>\n<li>The <code>references/</code> dir is the right home for: long rationalization tables,\noutput format templates, detailed sub-protocol steps, graph conventions.</li>\n<li>Splitting only helps if SKILL.md says <em>when</em> to read the reference file.\nReference files load only on an explicit link from the body — moving\nprose into <code>references/</code> without a pointer just relocates the tokens off\nthe visible budget rather than deferring them from the model's read.</li>\n</ul>\n<p><strong>Smell test:</strong> if the SKILL.md body has grown to the point where the Flow\nsection is buried below a long Inputs section and three flag tables, it is\ntime to factor.</p>\n<p>Provenance: the budget originated as an adaptation of Matt Pocock's\n&lt;100-line cap for his skills repo, and has since been restated in tokens\nagainst this repo's own measured prose density.</p>\n<hr>\n<h2>Iron Law / Red Flags / Rationalization-table template</h2>\n<p>Discipline skills (skills that enforce a process, not just explain a\ntechnique) follow this three-part structure. Apply it in a\n<code>## Discipline</code> section in the SKILL.md body, or in a\n<code>references/&lt;skill&gt;-discipline.md</code> satellite file when the body is already\nat budget.</p>\n<h3>Iron Law</h3>\n<p>One sentence. States the gate that must never be skipped. The Iron Law is\ndescriptive, not aspirational: it names what the skill <em>will</em> refuse to do\nwithout.</p>\n<p>Example shape:</p>\n<blockquote>\n<p><strong>Iron Law:</strong> No [output] without [prerequisite step] first.</p>\n</blockquote>\n<h3>Red Flags</h3>\n<p>A short list of signals that the Iron Law is about to be violated. These are\nthe observable pre-rationalizations — the moment before a step gets skipped.</p>\n<p>Example shape:</p>\n<blockquote>\n<p><strong>Red Flags</strong> — stop if you notice these:</p>\n<ul>\n<li>\"The tests will obviously pass after this change.\"</li>\n<li>\"I'll add the test in the next commit.\"</li>\n<li>[skill-specific patterns]</li>\n</ul>\n</blockquote>\n<h3>Rationalization table</h3>\n<p>A table enumerating the excuses an agent uses to skip the Iron Law step, with\nan explicit rebuttal for each. The table is adversarial by design: it assumes\nthe model will reach for a rationalization under pressure.</p>\n<table>\n<thead>\n<tr>\n<th>Rationalization</th>\n<th>Why it fails</th>\n<th>Required action</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>\"The change is obvious, tests would just mirror the code.\"</td>\n<td>A test that mirrors code catches regressions; that is its job.</td>\n<td>Write the test.</td>\n</tr>\n<tr>\n<td>[skill-specific row]</td>\n<td>[rebuttal]</td>\n<td>[required action]</td>\n</tr>\n</tbody>\n</table>\n<p>Keep the table to the rationalizations actually observed in practice (5-10\nrows maximum). An exhaustive list defeats the purpose.</p>\n<hr>\n<h2>Authoring review checklist</h2>\n<p>Before a skill ships, verify:</p>\n<ul>\n<li><input disabled=\"disabled\" type=\"checkbox\"> <strong>Triggers present.</strong> The description names concrete phrases the user\nmight say (not capability prose).</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> <strong>No time-sensitive information.</strong> Skill bodies must not embed version\nnumbers, dated pricing, or API endpoints that will rot. Point to docs\ninstead.</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> <strong>Concrete examples.</strong> At least one worked example exists — either\ninline or in a <code>references/</code> file.</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> <strong>References one level deep.</strong> The SKILL.md body points to\n<code>references/*.md</code> files; those files do not markdown-link further into their\nown sub-references. A partial <code>head</code>-style read of a reference file would\nsilently miss the tail of a hidden second hop. A link to a reference file\nthat is itself linked from a SKILL.md is a lateral citation, not a second\nhop, and passes.</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> <strong>Discipline skills have the Iron Law section.</strong> Any skill that enforces\na gate or a loop carries the three-part template above.</li>\n<li><input disabled=\"disabled\" type=\"checkbox\"> <strong>Dual-listed.</strong> The skill's directory appears in the\n<code>.claude-plugin/plugin.json</code> <code>skills</code> array. The CI check\n<code>tests/python/test_plugin_manifest.py::test_claude_plugin_manifest_matches_top_level_skills</code>\nenforces this.</li>\n</ul>\n<hr>\n<h2>Pressure-test-first authoring gate</h2>\n<p><strong>Iron Law: no skill ships without a failing-baseline subagent run first.</strong></p>\n<p>Before writing a new skill body:</p>\n<ol>\n<li>Construct a representative pressure scenario — a prompt that describes a\ntask the skill is meant to improve.</li>\n<li>Run a subagent on that scenario <em>without</em> the skill active. Capture the\noutput as the baseline.</li>\n<li>Identify the specific failure: what did the subagent do wrong, skip, or\nmisframe?</li>\n<li>Write the skill body to address that specific failure.</li>\n<li>Re-run the subagent with the skill active and confirm the failure is\ncorrected.</li>\n</ol>\n<p>A skill whose body was never tested against a failing baseline may fix a\nproblem the model does not actually have, or it may describe a workflow the\nmodel already follows without being told.</p>\n<hr>\n<h2><code>disable-model-invocation</code> frontmatter (candidate — not yet applied)</h2>\n<p>Matt Pocock's skills repo uses <code>disable-model-invocation: true</code> in the\nfrontmatter of pure-prompt skills (skills that execute immediately without\nre-prompting the model). The Claude Code frontmatter validator\n(<code>.github/scripts/validate_skills.py</code>) already allows this key.</p>\n<p><strong>Status:</strong> candidate-pending-harness-verification. Do not apply to any\neasy-cheese skill until the harness behavior is confirmed: what does the\nharness do when this key is set, and does it match the intended\n\"execute immediately\" semantics? Document the verification result here\nbefore applying.</p>\n","files":[{"path":"SKILL.md","sizeBytes":7850,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-10T16:34:33.309533Z","sha256":"F9A1D545330D95C851EAED995218A479805BDB192D9450584F7C71E8CB6DADB3","sizeBytes":3557},"review":null,"source":{"repositoryUrl":"https://github.com/paulnsorensen/easy-cheese","path":".agents/skills/skill-authoring","license":"MIT","commit":"39444e8d8e903466d736427c617234f94e0478d7","subtreeSha":"7847EB94335781BB5BD585E7A9CDD4400D244E8331FEC7E3036941448ADAE1D1","lastSyncedAt":"2026-09-20T13:50:30.291058Z"},"reviewedAt":"2026-09-10T16:36:51.000309Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/paulnsorensen/easy-cheese/tree/main/.agents/skills/skill-authoring"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install paulnsorensen-easy-cheese@llmmart"},{"target":"git","command":"git clone https://github.com/paulnsorensen/easy-cheese.git"}]}