Skill Authoring

Write a skill that actually loads, does one thing, and stays maintainable. Selection happens on the description, so most skill failures are description failures.

When to use

• Writing a new skill
• A skill exists and never fires
• The wrong skill fires on a request
• A skill set has grown past a dozen and collisions started

Inputs

• Reads: workspace/agents/<name>/brief.md, the context portfolio
• Needs from user: the procedure, the phrases a real person uses to ask for it, and the output shape

Workflow

1. Get the description right, because nothing else matters if it is wrong

Selection happens on the description alone. The body is invisible until after selection.

A description needs three things:

description: <what it does, in one clause>. Use when the user says
  "<literal phrase>", "<literal phrase>", "<sloppy real-world phrase>".
  <What it produces and where it writes.>

Use the literal phrases people actually type, including the ungrammatical ones. "our data is a mess" is a real trigger. "when the user requires data quality remediation" is not, because nobody says that.

State the output. A description that says what it writes helps both selection and the reader.

2. Write the negative boundary

Half of trigger problems are over-firing, not under-firing.

Do NOT use this skill when:
- <adjacent case> → use <other skill>
- <adjacent case> → do it inline, no skill needed

If two descriptions in your set could match the same sentence, one of them is wrong. Add a "for X, see Y" pointer to both.

3. Follow the anatomy

---
name: kebab-case, matches the directory name
description: as above
---

# Title

One or two sentences on what this does and the belief behind it.

## When to use
Bullets. Concrete situations, not abstractions.

## Inputs
- Reads: <files this expects to find>
- Needs from user: <what to ask for, in one batch>

## Workflow
### 1. <Numbered step>
### 2. <Numbered step>
Tables for reference data. Code blocks for output shapes and arithmetic.

## Output
- Writes: <exact path>
- Prints: <what appears in the conversation>

## Rules & quality bar
Bold-lead bullets. The non-negotiables. This is where the opinion lives.

## Related skills
- Requires / Hands off to / See also

4. One skill, one job

The test: can you state what it does in one sentence with no "and"? If not, it is two skills.

Symptoms of a skill that is doing too much: a workflow with more than about eight steps, two different output files, or a name containing "and" where the two halves are separable.

5. Manage the context cost

Every loaded skill occupies context.

• Long reference material goes in docs/ or references/. The skill points at it. This keeps the loaded footprint small and makes the reference reusable
• Templates go in templates/. Not pasted into the body
• Past roughly a dozen skills, add a router. One skill holds the routing table and loads exactly one child. Flat sets above that size collide
• State goes in files. Anything that should survive the session gets written to workspace/

6. Write the rules section like you mean it

The "Rules & quality bar" section is what makes a skill more than a description of a process. It is where you say the unwelcome thing: what to refuse, what to always check, what people get wrong.

A skill with a vague rules section produces vague output. Every rule should be checkable.

7. Verify it loads

Never assume discovery. Skill loaders fail silently.

[ ] Directory name matches the frontmatter name
[ ] The description contains phrases a real user would type
[ ] It appears in a fresh session
[ ] It fires on the intended phrase
[ ] It does NOT fire on the adjacent phrase you wrote a boundary for
[ ] Every path it references exists

The last two are the ones people skip, and they are the two that produce the "it works on my machine" failure.

Output

• Writes: skills/<name>/SKILL.md
• Uses: templates/skill-template.md
• Prints: the skill, plus the verification checklist result

Rules & quality bar

• The description is the product. Spend real time on it
• Literal user phrases, including sloppy ones
• Every skill has a negative boundary
• One skill, one job. No "and" in the sentence that describes it
• Reference material lives outside the skill body
• Router pattern past a dozen skills
• Verify it loads and verify it does not over-fire. Both
• Never hardcode positioning, ICP, or guardrails. Read them from the context portfolio

Related skills

• Requires: agent-scoping, context-portfolio
• Hands off to: agent-guardrails, then agent-rollout
• See also: docs/build-surface.md on choosing between skill, subagent, hook, and script