skill-writer

Skill Writer

A guide for writing SKILL.md documents that earn their tokens. A skill lives in its own directory — skills/<category>/<name>/SKILL.md — and is load-on-demand guidance: the agent sees the one-line description in its index always, but the full body only enters context when the agent decides the situation calls for it. Write for that moment: high signal, no filler.

This skill is harness-neutral. It assumes only the common agent-skill format: a directory with a SKILL.md carrying YAML frontmatter, optional scripts/, references/, and assets/ subdirectories.

When to use

• You are adding a new skill directory.
• You are substantially rewriting an existing skill.
• You are deciding whether a piece of work belongs in a scripts/ script or a references/ checklist.
• You are adapting an external skill for import.

Skip this for a one-line correction to an existing skill — run skill-scanner instead to confirm you have not introduced new issues.

Frontmatter — every skill starts here

Every SKILL.md begins with YAML frontmatter. Two fields are required:

---
name: my-skill
description: One-sentence hook that helps the agent decide whether to load this
---

Rules:

• name matches the directory: skills/<category>/my-skill/SKILL.md means name: my-skill. Lowercase, hyphenated, matching the regex ^[a-z0-9][a-z0-9-]*[a-z0-9]$.
• description is one sentence, high-entropy, third person, and keyword-rich — it carries both what the skill does and when to reach for it. Read it as "the agent has 200 skills to choose from — why this one, now?".
  • Good: "Deploy-test-debug retry strategy — triage failures, bound retries, escalate when stuck."
  • Bad: "A skill for fixing things" (too vague); "iterate-fix-retry-loop-strategy-for-autonomous-deploy-cycle" (keyword soup).
• Optional fields some toolchains read: allowed-tools (least-privilege — see hygiene below), license, and a metadata: block (author, version, source/provenance). Keep them minimal and accurate.