Reference Patterns
Use these patterns as review lenses, not mandatory sections for every skill. Recommend one only when it matches the skill's failure mode, workflow risk, or output contract.
Trigger / Protocol Split
Keep frontmatter description focused on observable trigger conditions. Put the execution protocol in the body so agents load the full skill before acting.
Example: description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes; body owns the debugging phases.
Iron Law + Rationalization Firewall
Use for discipline skills where an agent may knowingly skip the rule under pressure. Pair a non-negotiable rule with no-exception wording, common excuses, and red flags.
Example: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE, followed by a table mapping "should work now" to "run the verification".
Step 0 State Detection
Start operational skills by detecting the current state before creating, deleting, delegating, or validating anything. This prevents duplicate setup and wrong-environment actions.
Example: before creating a worktree, inspect git rev-parse --git-dir, git rev-parse --git-common-dir, current branch, and submodule state.
Gate Function
Turn important claims into a small evidence gate: identify what proves the claim, run the current command, read the output, then state only what the evidence supports.
Example: before saying tests pass, run the full relevant test command, inspect exit status and failures, then report the command and result.
Finite-State Workflow
Model complex workflows as ordered phases with entry criteria, exit criteria, and stop/loop-back behavior. Avoid unordered advice when sequence matters.
Example: debugging moves through investigation, pattern analysis, hypothesis testing, and implementation; a failed fix loops back instead of piling on another guess.
Controller / Implementer / Reviewer Protocol
For multi-agent workflows, define the controller role, subagent roles, handoff artifacts, status values, and who owns final consistency.
Example: implementer returns DONE, DONE_WITH_CONCERNS, BLOCKED, or NEEDS_CONTEXT plus a report file; reviewer reads the task brief, report, and diff package before returning a verdict.
Review Calibration Contract
Reviewer prompts should constrain scope, evidence, severity, and output shape. This keeps reviews from becoming generic advice or broad codebase crawls.
Example: reviewer is read-only, diff-scoped, does not trust the implementer report, categorizes findings by severity, and starts with a spec-compliance verdict.
Pressure Scenario Testing
Validate behavior-changing skills by first observing baseline failure without the skill, then retesting with the skill under realistic pressure.
Example: combine time pressure, sunk cost, authority, and explicit options such as "delete and restart with TDD" versus "commit now, test later".
Output Contract Slots
For plans, reports, reviews, and templates, prefer required slots over prose reminders. Slots make omissions visible and parser-sensitive fields stable.
Example: a task plan requires Files, Interfaces, exact steps, commands, expected output, and a self-review check; TODO, TBD, and "similar to above" are invalid.
Exact Option Menu
When the next step requires a user decision, present a fixed menu tied to concrete follow-up behavior instead of an open-ended "what next?" prompt.
Example: after branch work, offer exactly merge locally, push and create PR, keep as-is, or discard; detached HEAD removes the local-merge option.