SuperAPI AI Directory

skill-writer

Coding & development

View repository

Updated 11-05 16:17

About this skill

Skill Writer

Generate correctly structured SKILL.md files for the Claude Code skill ecosystem. Every skill follows the same frontmatter convention and directory structure.

When to Use

  • Creating a new agent role skill
  • Creating a new workflow or meta skill
  • Reviewing existing skills for spec compliance
  • Adding a role to an orchestrated build

Skill Directory Structure

skill-name/
├── SKILL.md              # Required — frontmatter + instructions
└── references/           # Optional — loaded on demand
    └── detailed-guide.md

Progressive Disclosure

Skills use three-level loading:

  1. Metadata (~100 tokens) — name + description, always in context
  2. SKILL.md body (≤5,000 words; soft warning at 500 lines) — loaded when skill triggers
  3. References (unlimited) — loaded on demand via explicit reads

Keep SKILL.md bodies concise. Move detailed checklists, templates, and reference tables to references/ with clear pointers.

Creating a New Skill

Step 1: Choose the Skill Type

Type Directory Purpose
Agent role roles/{name}/ Implementation agent for orchestrated builds
Meta skill meta/{name}/ Tools for the skill ecosystem itself
Workflow workflows/{name}/ Cross-cutting processes
Contract contracts/{name}/ Integration contract management
Orchestrator orchestrator/ Lead coordinator (singleton)

Step 2: Write the Frontmatter

Every SKILL.md starts with YAML frontmatter. See references/frontmatter-spec.md for the complete field reference.

Required fields:

  • name — kebab-case, max 64 chars. claude-* / anthropic-* prefixes are reserved by Anthropic; use them only as a documented exception when the skill targets the corresponding Anthropic product (e.g., claude-design-brief).
  • version — semver (start at 1.0.0), top-level
  • description — [What] + [When] + [Capabilities] anatomy (≤200 chars target, 1024 hard ceiling)

The description is the primary trigger mechanism. Write it "pushy" — enumerate contexts where the skill should activate. See references/description-patterns.md for templates and the 3-slot anatomy.

Step 3: Write the Body

Structure the body around:

  1. Role statement — one paragraph defining what this agent/skill does
  2. Inputs — what parameters it receives
  3. Process — numbered steps, imperative voice
  4. Coordination rules — how it interacts with other agents
  5. Guidelines — principles and common pitfalls

Writing craft (the four rules that keep a body short and reliable):

  • Anchor on a leading word. Hang the skill's behavior on one strong pretrained concept the model already knows ("adversarial", "triage", "postmortem") instead of restating a three-part definition at three different sites. If the same idea appears in the description, the intro, and a step, collapse it to the one word that carries it.
  • Delete no-op sentences whole. Any line the model already obeys by default ("be helpful", "write clean code", "consider edge cases") is pure context cost. Delete the entire sentence — don't trim it to a shorter no-op.
  • State the target behavior, not the bare prohibition. "Don't X" leaves the model to guess the replacement; "do Y (because Z)" names it. Keep a prohibition only when the forbidden form itself is the sharpest anchor (the Forbidden: anti-pattern naming convention).
  • Price every warning you keep. A warning that names its real rework cost ("burns the agent's entire context", "rework surfaces a wave later") gets weighed; an unpriced one reads as style advice and gets skipped under pressure. See Cost-Tagged Anti-Patterns in references/patterns.md.

For agent role skills, also include:

  • Step 0: Read Contracts — every role skill should start by reading contracts and domain rules before any implementation
  • Ownership — directories/files owned exclusively, with note that orchestrator prompt takes precedence over frontmatter defaults
  • Off-limits — what this agent must never touch
  • Right-sizing — guidance on adapting to project complexity
  • Validation — link to references/validation-script-pattern.md for how to wire a validation step into the new skill's body

Step 4: Create Reference Files

Move detailed content to references/:

  • Validation checklists with specific commands
  • Templates and examples
  • Detailed technical guides
  • Tables longer than 20 rows

Reference files from the body with guidance on when to read:

For the complete validation procedure, read `references/quick-checklist.md`
before reporting done.

Step 5: Add a Triggering Test

Every skill must carry a concrete triggering test — at least one example user phrasing that MUST activate the skill, and ideally one near-miss that must NOT. This is how you verify the description actually triggers (not just that it reads well). Record it in the skill (e.g. a short "Triggering test" note or a row in references/quick-checklist.md) so reviewers can re-run it.

Step 6: Validate the Skill

Work one focused change at a time — make a single edit, re-validate (lint + the triggering test below), then move to the next. Don't sweep many unrelated changes into one pass.

  • Frontmatter has all required fields
  • name is kebab-case. If it starts with claude- or anthropic-, that's a documented exception (skill targets the corresponding Anthropic product)
  • No < or > anywhere in frontmatter
  • Description is ≤200 chars (target) and "pushy"; never exceeds 1024 chars (ceiling)
  • Body is ≤5,000 words (soft warning past 500 lines)
  • File ownership doesn't overlap with existing agents (check v1.1 resolved conflicts)
  • Directory ownership takes precedence over pattern ownership
  • Reference files are linked from the body
  • No duplicate content between body and references
  • A triggering test is recorded (≥1 phrasing that must trigger; ideally one near-miss that must not)

Step 7: Earn the Context Cost (optional, recommended for non-trivial skills)

Optionally compare behavior with vs without the skill — a quick baseline eval on one or two representative prompts — to confirm the skill measurably improves the output and earns the tokens it adds to every context. Skip for trivial skills; do it for anything substantial.

Common Mistakes

  • Vague descriptions — "Helps with backend stuff" won't trigger. Be specific.
  • Body too long — Approaching 5,000 words or 500 lines? Move content to references.
  • Missing ownership — Agent roles must declare owned and off-limits files.
  • Overlapping ownership — Two agents can't own the same directory. Directory ownership takes precedence over pattern ownership (see references/frontmatter-spec.md §Ownership Resolution Rules).
  • Ignoring resolved conflicts — Check references/frontmatter-spec.md §Resolved Conflicts (v1.0 → v1.1) before declaring ownership of contracts/, .claude/handoffs/, CLAUDE.md, README.md, or tests/performance/.
  • Hardcoded project details — Global skills never change per project. Use profile.yaml.

Reference Files

  • references/frontmatter-spec.md — Complete field reference with types, rules, and examples
  • references/description-patterns.md — Templates for writing effective trigger descriptions
  • references/body-template.md — Anthropic's recommended SKILL.md body structure, plus per-skill-type deviations (agent roles, meta, orchestrator, workflow)
  • references/patterns.md — Five architectural skill patterns (Sequential Workflow, Multi-MCP Coordination, Iterative Refinement, Context-Aware Tool Selection, Domain-Specific Intelligence)
  • references/quick-checklist.md — Pre-ship checklist: frontmatter, description, body length, triggers, cross-references
  • references/performance-notes.md — When and how to add a Performance Notes section to combat model laziness
  • references/validation-script-pattern.md — How to author and wire a deterministic validation script for a skill