Skill Authoring

How to author skills correctly

A set of rules based on the Agent Skills specification + practice. Verified against real skills.

1. Frontmatter (required fields)

---
name: my-skill
description: Use when [triggers/symptoms/contexts]. [what it does + when to apply]
---

2. Directory structure

skill-name/
├── SKILL.md            # required
├── scripts/            # optional: executable scripts
├── references/         # optional: details, «read when X»
├── assets/             # optional
└── any other files/folders — allowed

• From SKILL.md reference files with relative paths from the skill root.
• Progressive disclosure: SKILL.md < ~500 lines; details go into references/ with a pointer «read this when X happens».

3. Script bundling (scripts/)

1. First check for an existing tool: npx, uvx, pipx, bunx — take an existing one, write your own only when none exists.
2. If you bundle a script, it must be self-contained: document dependencies in SKILL.md or compatibility.
3. Agent-safe design:
   • NO interactive prompts — the agent will hang on a TTY. Input only via arguments.
   • --help with usage; clear error messages.
   • Structured output: result to stdout, diagnostics to stderr.
   • Idempotency; --dry-run for destructive operations.
   • Predictable output size (agents truncate ~10–30K characters).

4. Best practices and antipatterns

Do:

• Small, composable, like a function: one coherent task.
• Description in the imperative: «Use when …», list the triggers. Agents under-trigger.
• Add what the agent does not know; drop what it already can do.
• Gotchas sections — the most valuable content; checklists for multi-step processes; output templates.
• Defaults, not menus; procedures, not declarations; explain «why».
• Calibrate detail to fragility: for fragile operations — prescriptively.

Do not:

• Do not stuff code into SKILL.md — move it to scripts/.
• Do not describe the workflow in description.
• Do not give many equal options without a default.
• Do not generate generic content without subject knowledge.

5. New skill template

---
name: my-skill
description: Use when [symptoms/contexts]. [what it does + when to apply, 1–1024 chars.]
license: MIT               # optional
compatibility: Requires X  # optional
---
# What it does (1–2 sentences)

## When to use / when NOT to use
## Workflow (numbered, imperative)
## Gotchas
## Available scripts (relative paths from the skill root)
## References (pointers «read when X»)

6. Turning a session into a skill (the former /learn flow)

The raw material is what happened in this chat (or a named directory/procedure/URL) — not a skill-format question, and not a conclusion to remember (that is dev-wiki/findings).

1. Isolate the repeatable procedure. What did you actually do that a fresh session would have to rediscover? Steps in order, with the "why" behind non-obvious decisions. One-off facts are NOT skills → memory instead; general knowledge the agent already has is NOT a skill (YAGNI).
2. Trigger test before writing. In a fresh session, would the description fire for the natural phrase a user would say? No plausible trigger → stop, don't write it. The description is the only thing a future session sees.
3. Draft SKILL.md by the rules above: numbered imperative procedure, defaults (not menus), gotchas — the most valuable section.
4. Choose the location. Portable (any machine/project) → kit skills/<slug>/, subject to English, file-size and review checks. Machine/user-specific → the harness's user skills dir (e.g. ~/.claude/skills/), which does not propagate. Creating a skill does not itself authorize a commit or deployment to installed harnesses; apply AGENTS.md action authorization.
5. Verify and candidate state before broad promotion. Frontmatter delimiters, name == folder, description within limits; trigger test against the natural phrase. A newly distilled procedure starts as a candidate:
   • Promotion criteria: promotion to default or mandatory policy requires replaying the originating case, at least one nearby negative case (where the procedure must NOT fire or alter behavior), and at least one held-out case.
   • Retirement criteria: skills are evaluated and retired by post-install opportunity/use and measurable contribution to correct outcomes, not raw read counts. Gotchas: don't over-generalize — encode the procedure that exists, not the class of procedures; Russian belongs only in trigger words; scripts stay in scripts/, never inline; a skill that was wrong once is fixed like code — edit + verify against the same case.