I published a SKILL.md and nobody installed it. Here’s how to write one people actually keep

Description and use

The author published a SKILL.md that was never installed because it was descriptive, not instructive. He created a five‑part method—title, trigger, steps, counter‑examples, boundaries—to write skills that actually change agent behavior.

Problem

A developer published a Skill file (SKILL.md) that was never installed or used by agents, revealing that the skill was descriptive rather than instructive.

Outcome

By applying the five‑part method, the author can create SKILL.md files that are actually installed and used, rather than decorative.

Workflow

• 1. Write a concise, claim‑based title that states what the skill does. 2. Craft a trigger description that specifies when the agent should load the skill. 3. Ensure every body line removes a choice the agent would otherwise make. 4. Include counter‑examples and boundaries to clarify limits. 5. Test the skill by checking that it changes agent behavior in the intended scenario.

Evidence

"Nice write-up. But my agent didn’t do anything differently than it would have anyway."

Source

A skill earns its place by removing a choice the model would otherwise make badly. If it doesn’t remove a choice, it’s a preamble.

Source

The agent reads the description first, and only if the description fires does it pull in the body.

Source