skill-authoring

Skill Authoring Protocol

EXTREMELY_IMPORTANT: This is a MANDATORY protocol, not a suggestion. Follow every step. Do not skip steps. Do not combine steps. Do not summarize. Work through each step in order.

You are creating a skill — a behavioral protocol another agent will be trusted to follow. A weak skill is worse than no skill: it burns context, triggers on the wrong tasks, and trains users to ignore the ones that matter. Build it in this order.

STEP 1 — Name the gap

State in one sentence the specific reasoning failure this skill prevents, and cite a concrete incident where an agent without it went wrong. If no incident exists — yours, the user's, or a documented pattern — say so and ask whether the skill should exist at all. A skill nobody has failed without is a reference document waiting to happen.

STEP 2 — Design the trigger before the body

The frontmatter description is the enforcement layer: it is the ONLY part loaded at all times — the body loads after invocation, so a vague description means the body never runs. Write the description as a trigger, then test it:

1. List the task shapes where this skill MUST fire, concretely.
2. List adjacent task shapes where it must NOT fire (the false-positive set).
3. Write at least 3 prompts that should trigger it and 3 that should not, and check the description text ALONE classifies all of them correctly. Fix the wording, not the test set, until it does.

Use imperative mandatory voice ("You MUST invoke... Do NOT...") — passive descriptions ("useful for...") measurably under-trigger.

STEP 3 — Design the protocol body

Every step must be an imperative action ending in a check the agent can fail — "Do X; if Y, stop" — never "consider X." Apply the earn-its-place test: if deleting a step would not change the agent's output on the STEP 2 trigger prompts, delete it. More steps is dilution, not rigor.

Then choose exactly ONE <HARD-GATE>: the single thing this skill refuses to let happen, stated as an observable condition ("do NOT claim the bug fixed without a test observed failing pre-fix"), not a mood ("be thorough"). Add a structured output block so results are auditable, and confidence levels if the skill produces an analysis. Keep the whole file under 150 lines — past that, it is doing two jobs; split it.