Skill necessity gate

skill-necessity-gate

Most ideas for new skills should not become skills. Every skill you add costs context space in every conversation, and most candidates are better served by a different layer — or by nothing. This checklist catches them: six gates, run in order, and a candidate must pass all six. The default answer is "not a skill," and the goal is a correct decision, not an approved one.

This skill is itself a deliberately-invoked procedure (disable-model-invocation: true) — you run it when contemplating a skill. That is the framework applied to itself.

When to run

• Someone (incl. you) says "let's make a skill for X" / "should this be a skill?"
• Auditing an existing skill for whether it earns its context cost.
• Deciding skill vs CLAUDE.md vs memory vs MCP vs pre-tool hook vs named workflow.
• A skill library feels bloated (see Mode B in absence-detection.md).
• Before building any instrument (harness, miner, metric, oracle, eval): instruments are skill-shaped bets and run the same gates (GD-11) — prior-art sweep at Gate 0, recurrence at Gate 1, and at Gate 2 name the pending decision the output would change; no decision, no build.

Mode A — Gate a candidate (the core procedure)

Run the six gates IN ORDER. A candidate must pass ALL of them. Stop at the first failure and route it where the gate says. Earlier gates are cheaper and reject more.

Gate 0 · Layer triage — is this even skill-shaped? (most candidates die here)

• Is it a fact / stable preference / repo rule? → CLAUDE.md or memory. NOT a skill.
• Is it access to a system/data (API, DB, service)? → MCP / connector. NOT a skill.
• Is it trivially discoverable from the codebase (which build tool, file layout)? → let the agent read the repo. NOT a skill and NOT CLAUDE.md — encoding it elsewhere rots.
• Is it already supplied by the harness at point of use, or a recurring fan-out orchestration? → nothing (redundant, rots) / a named workflow script. NOT a skill.
• Is it a multi-step procedure / reusable capability? → continue.
• Then: relevant every session (→ push into CLAUDE.md, accept always-on cost) or only sometimes (→ a skill, loaded only when needed, is the right home)? Only "sometimes" continues.

Gate 1 · Recurrence — does the pattern actually recur?

• Criterion is frequency, not complexity. Reject the "too simple" fallacy — trivial prompts you type constantly are prime skills.
• Don't predict — measure. Park the candidate in the skills folder and count how often you actually reach for it. Promote on demonstrated "freaking often" frequency.
• Count occasions, not artifacts. Recurrence mined from agent transcripts must be deduped by run: one orchestrated fire spawning N parallel seats is n=1, not n=N.
• If you keep running two existing skills together → MERGE them, don't add a third.
• Unproven + unmeasured → park & observe, do not author yet.

Gate 2 · Worth — does value clear cost? Measure, don't argue.

• Cost: a model-invocable skill adds ~100 always-on tokens to the system prompt and competes in the skill-list budget (~1% of context; least-used descriptions get truncated then dropped at scale). Live skills also dilute each other's attention. (A procedure — Gate 3 — costs ZERO standing tokens, so this gate is lenient for procedures.)
• Benefit — eval first: build the eval BEFORE the docs so you solve a real problem, not an imagined one. Run with-skill vs without-skill on pass-rate / tokens / time — minding the traps that make naive skill benchmarks lie (governing-dynamics.md GD-11).
• Author only if measured benefit > cost. Exception: a zero-cost procedure that reliably enforces a process you care about passes on control value alone.

Gate 3 · Invocation topology — if it should exist, what KIND?

Deciding question: who does the strategic thinking?

• Skill dictates how/what (planning, steps, the thinking), or has side effects (deploy/commit/send) → PROCEDURE, human-invoked. Set disable-model-invocation: true. "Do not delegate thinking to the model." Zero standing cost; you stay the strategic general.
• Background reference the model should pull when relevant → ABILITY, model-invoked (default). Pay ~100 tokens; the description IS the router (Gate 5).
• Two flags → four states: disable-model-invocation × user-invocable.
• This is partly a user-values call. SURFACE the budget math + the control tradeoff and ASK; do not auto-decide auto-vs-manual.
• Autonomy axis (GD-10): "will this run inside an autonomous loop?" If yes and the loop must fire it, do NOT set disable-model-invocation — in Claude Code such a skill goes inert in /loop (arrives as plain text). Keep it model-invocable with a sharp description + verification, or relocate it upstream as a human backlog gate. Full supplement: loops-and-autonomy.md.

Gate 4 · Statefulness — cross-session memory?

• Must it survive a blank-slate new session? → the skill's job includes enforcing read/write of durable file state. Design the persistence contract explicitly.
• If not → keep it stateless; don't add machinery you won't use.

Gate 5 · Shape for low cost — once you commit

• The description is the highest-leverage tokens. Third person, "what it does + when to use it"; it competes with every other skill's description for dispatch. Write it as a ROUTER.
• Concise enough to force a posture (a 4–5 sentence skill can be powerful). Actionable procedure > documentation. Body < 500 lines; progressive disclosure, references one level deep.
• Prefer positive procedures + deterministic enforcement over prohibitions (GD-9). "Negative" instructions ("do not use npm") burn budget and are non-deterministic — use a pre-tool hook, not a prompt-based taboo.

Refusal predicate (the fast "no")

Reject/route when it's: a fact (→ memory/CLAUDE.md) · access (→ MCP) · discoverable from the repo (→ read the code) · harness-supplied at point of use (→ nothing) · a fan-out orchestration (→ named workflow) · always-on (→ push) · recurrence unproven (→ park & observe) · better merged (→ merge) · benefit ≤ cost for an ability · delegating strategic thinking the human should own · a "ball of mud" of abstract rules · mostly negative instructions (→ hook).

Other modes

• Mode B — library audit / anti-bloat (incl. the retire-a-skill criteria) and Mode C — absence detection (what skills are MISSING?): see absence-detection.md.

Discipline vs implementation

The discipline (stable contract): six ordered gates, refusal predicate, default-to-"not a skill", measure-don't-argue, GD-11. The implementation surface (illustrative — swap for your runtime): the ~100-token / 1%-of-context numbers (Claude Code, 2026), frontmatter flag names, /loop semantics, tools named in examples.

Provenance

Evidence behind every gate (Matt Pocock's methodology triangulated against Anthropic's skill docs + IFScale): governing-dynamics.md. Record surprises in gotchas.md (append-only).