How to Write a High-Leverage SKILL.md

The six steps

1. Write the trigger first

Before any instructions, write the frontmatter description as trigger conditions: the task shapes and phrases that should fire this skill, and the ones that must not.

description: Use when encountering any bug, test failure, or
  unexpected behavior, before proposing fixes. Do NOT use for
  planned refactors or feature work.

If you cannot state when it fires, the skill doesn't know either. Marketing language here ("a powerful debugging assistant") is the number-one cause of skills that never trigger.

2. State the purpose as a prevented failure

"Prevents the agent from patching symptoms before finding the root cause" beats "improves debugging quality." A concrete failure gives the agent (and reviewers) a test: does following this skill make that failure impossible?

3. Write one-action-per-step instructions

Compound steps are where agents improvise. "Reproduce the bug and identify the cause" is two steps wearing one number; split it. Each step should name an action and the observable result that proves it happened.

4. Add verification the agent must run

A skill without a verification section cannot refuse to accept bad work. Make each check runnable or inspectable:

## Verification
- [ ] The failing test now passes: run the suite, read the output
- [ ] No other tests broke: full suite exit code 0
- [ ] The fix addresses the diagnosed cause, not the symptom

This is what separates a skill from a wish. It is also the dimension the ecosystem most underinvests in: evaluation readiness is the weakest average score in the Agentiquette index.

5. Declare boundaries

Never-do rules are the governance layer inside the skill, and they are what make auto-triggering safe. "Never force-push", "never modify the test to make it pass", "never touch generated files." If the skill can act destructively, gate it or exclude it here.

6. Finish with one realistic example

One fully worked example: real-shaped input, the steps applied, the verified result. Examples disambiguate faster than any amount of instruction prose, and answer engines extract them.

Then test the trigger

Write three paraphrases of a task the skill should handle. Run each in a fresh session. Three fires out of three is a pass. Anything less, rewrite the description, not the task. This five-minute test catches the failure that otherwise stays invisible forever: silent non-use.

Calibration

Length: as short as completeness allows; most high-leverage skills fit in one to three screens. Scripts: bundle them when mechanics are better executed than described, and remember they make your skill a code-review surface for adopters. Tone: imperatives, no hedging; the agent will mirror your precision.

Start from the SKILL.md template, which carries this structure with annotated fields, and run the evaluation checklist against your own skill before asking anyone else to adopt it.