Why_SKILL.md_Is_the_Wrong_Default

This article zooms in on one surface from Skill Architecture as the Next Frame After Prompt Engineering. Read that piece first if the four-layer model - CLAUDE.md cascade, SKILL.md, hooks, subagents - is new to you.

In April 2026, I closed a codification programme that turned four workflow procedures into formally specified skills. Handoff, decision logging, brief formatting, and new repository setup each got a SKILL.md file - a self-contained procedure with a trigger condition and a gate. The more interesting list is what didn't make the cut. Dozens of candidates fell away. Not because they weren't important. Because they didn't need the ceremony.

A skill is expensive to invoke. It requires an agent to recognise that this moment calls for the procedure, locate the file, read it, and execute step-by-step. A CLAUDE.md rule that fires on every turn is structurally superior to a skill the user has to summon - because the rule can't be forgotten.

Ask the right question first: not "should this be codified?" but "which layer does this knowledge naturally inhabit?" (as the skill architecture piece maps in full). Bias toward the lightest layer that works. A rule that governs every agent spawn on every project belongs in the always-on layer. A procedure that runs three times a year when circumstances demand it belongs in skills. Conflating them costs clarity.

The_Four_Criteria,_and_Why_One_Matters_Most

Four conditions favour SKILL.md promotion - but one separates skills from well-written CLAUDE.md rules. Repetition: has this procedure run 3+ times? Shape: are there discrete steps with a clear entry and exit? Trigger clarity: can the agent reliably know when to invoke it? Gate: is there a confirmation, an irreversibility check, or an idempotency verification that benefits from formalisation?

The first three are necessary. The gate is decisive.

Any procedure that passes repetition, shape, and trigger clarity but has no gate belongs in a standing reference document or a CLAUDE.md rule. The gate is what justifies the ceremony. Without it, you have a checklist with extra steps.

The_Lived_Evidence

The /decision skill exists because decisions are binding policy. Once an entry lands in decisions.md, it is locked - not reversible, not negotiable. The skill's entire architecture is built around that irreversibility. Step 4 is a non-skippable confirmation gate: the Owner must explicitly ratify the decision before the session commits the entry. Remove that gate and the skill collapses. It would be better as a CLAUDE.md rule - "log cross-project decisions" - firing ambiently whenever one arises. The ceremony serves no purpose without the gate.

Model tiering is the inverse case. The rule - which agents run on Sonnet, which on Haiku - has repetition (every agent spawn), shape (which model, when to override), and trigger clarity (every invocation). It has no gate. There is no confirmation step, no irreversibility, no idempotency check that changes the outcome by running through the procedure. A /check-model skill would add friction without benefit. The rule lives in CLAUDE.md, fires on every spawn, and doesn't require invocation. That's the right layer.

The_Closing_Claim

The gate is the point. If your skill doesn't have one, you wrote a checklist with extra steps. The discipline of skill promotion isn't about how complex the procedure is or how often it runs. It's about whether formalising the confirmation changes the outcome. That's a narrow bar. It should be.