Skill author guide

A skill is a contract between you and an agent. This one explains how to write a contract the agent keeps — and that passes emdly review the first time.

When to use

• Before writing your first skill. Load it into your agent and ask it to draft one with you.
• When a submission was bounced — the review checklist at the end is what reviewers use.

Anatomy of a skill that works

1. Title — the H1 is the skill's name in words.
2. One-paragraph purpose — what job it does and what it refuses to do. If this paragraph could describe five different tools, keep writing.
3. When to use — 2–4 concrete situations. Agents use this to decide whether to load you at all.
4. Input — what the skill expects to be given. Naming the inputs is half the reliability.
5. Process — numbered steps in the order the agent should take them. Each step produces something the next step uses.
6. Rules — the binding constraints. See below.
7. Output format — a literal example in a code block. Agents copy shapes far better than they follow descriptions.
8. Edge cases — the three inputs that would tempt a shortcut, and what to do instead.
9. License — a ## License section with an SPDX id. MIT is the default.

Rules vs. preferences

A rule is something the agent must do even when it seems unhelpful in the moment. Write rules as absolutes with the reason: "Never invent acceptance criteria — propose them and label the proposal." A preference ("prefer short sentences") is fine but goes in a separate line; mixing the two teaches the agent that rules are negotiable.

The rules that matter most in practice:

• What not to invent. Name the things that must come from the input (numbers, quotes, file names, decisions).
• What to do with uncertainty. "Flag it" beats "guess" every time; say how to flag.
• Scope of action. If the skill can run commands, say which ones and which need a human.

Output contracts

Give a real example, not a schema. Include the hard parts: an empty case, a flagged item, a number with its source. Then test it: run the skill on three inputs and check that the output matches the example's shape exactly. If it drifts, the example is ambiguous — fix the example, not the prose.

What reviewers bounce

• No license line.
• A prompt, not a skill: one paragraph of "you are a helpful…" with no process or output.
• Instructions that override the visible rules, hidden text, or anything that sends data outside the task. These are blocked automatically.
• Urgency or persuasion tricks in outreach skills ("say the offer ends today").
• Credentials in the file. Skills are public; keys live in the agent's configuration.
• Copy-pasted tool output instead of instructions.

Review checklist (self-check before submitting)

• Someone who has never seen my tooling could run this from the file alone.
• Every "never" has a reason and an alternative.
• The output example includes a flagged/empty case.
• Nothing in the file asks the agent to fetch, post or contact anything the task did not mention.
• ## License present.

License

MIT