| name | plugin-authoring |
| description | How to structure a Claude Code plugin so a Haiku-class model executes it reliably — router stubs, phase files, hard prompt budgets, externalized state, verdict contracts, hook patterns, and the done-bar. Use when / Trigger: creating a new plugin for this marketplace, writing or restructuring any SKILL.md / command / agent / hook, or porting a frontier-era plugin to small-model form. |
Plugin authoring for small-model execution
A plugin here is not a prompt collection — it is compiled process: every file
assumes the executing model cannot size its own rigor, hold long context, or
honestly self-report. The design rationale lives in the marketplace docs
(gap model,
mechanisms M1–M9); this skill is the
authoring rulebook. This plugin itself follows every rule below — read its own
files as a live example.
The rules
-
Budget first. Hard line limits, lint-enforced
(ADR-0006):
| Artifact | Max lines | Note |
|---|
| execution-path prompt (SKILL.md body, phase file, agent) | 150 | one decision per file |
| command router stub | 40 | dispatch only, no logic |
| hook-injected rule card | 20 | one rule, one contrast |
| reference file | 200 | loaded ONE at a time, never bulk |
Instructions that must survive go at the top or bottom of a file, never
the middle. If you're fighting the budget, you're writing two files.
-
Stub-and-phase anatomy. A command is a router: frontmatter + "read
run-state, load references/phase-<n>-<slug>.md, execute, checkpoint."
Each phase file is self-contained — it re-states its own inputs and output
contract, assuming nothing else is in context. Copy
templates/command-stub.md. Full anatomy:
references/structure.md.
-
No judgment verbs on the execution path. Grep your draft for
assess|appropriate|when it matters|right-size|if needed|thoroughly|carefully|use judgment|as necessary|sensibly.
Every hit gets compiled into a table, a vote, an artifact, or an escalation
— the judgment-compilation skill owns the recipes. Zero hits is the bar,
not few.
-
Externalize state for anything multi-step. No step may depend on
conversation history. Steps live as run-state rows
(runtime-state); every phase
prompt opens with the re-orientation preamble (read the step brief, read
ONLY the files it names) and declares an attention contract — an
explicit read-list. Resume = re-read state.
-
Verdict agents emit contracts, not prose. JSON only, enumerated
statuses, default-negative (failed unless evidence), one entry per
criterion with a 0-based index, an evidence field carrying attached probe
output, and objects kept small (one lens per invocation when lenses > 2).
Copy templates/agent-verdict.md. Probes are
pre-written by YOU at design time — the executing model runs them, it never
invents them.
-
Hooks detect; cards instruct; gates validate artifacts. Detection is
hook-side (regex on prompts / tool events in hooks.json) — never "use
when you feel tempted." The injected payload is a ≤20-line rule card
(templates/rule-card.md). An enforcing hook may
only block on something a script can validate: a file exists, a schema
passes, an exit code is 0 — never on asserted intent.
-
Every threshold ships with a fixture. Any number you invent (a tier
cutoff, a vote count, a cap) lands with an eval fixture proving the
behavior at the boundary — expected artifact shape in
tests/fixtures/<plugin>/. A threshold without a fixture is a guess wearing
a config file.
-
Manifest discipline. .claude-plugin/plugin.json per
templates/plugin.json; all marketplace manifests
carry the same version, patch-bumped every release; any hook or runtime
change REQUIRES a version bump (plugins deploy from a version-keyed cache —
a fix with no version delta never goes live).
Done-bar (before calling a plugin done)
Files in this skill
