# Skill Writer

> Generate new SKILL.md files conforming to the ecosystem's frontmatter spec and structure conventions. Use when creating a new agent role, meta skill, workflow skill, or contract skill — anything that needs a SKILL.md scaffold. Trigger on "create a skill", "new agent", "write a SKILL.md", "scaffold a skill", "add a role to the skill ecosystem".

- Skill: `ivy00johns/skill-writer` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add ivy00johns/skill-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ivy00johns/skill-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ivy00johns (https://skillmd.com/u/ivy00johns)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ivy00johns/skill-writer

---


# 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

```text
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.

**Declare portability explicitly.** Set `requires_claude_code: false` unless the skill genuinely needs Claude-Code machinery (Agent-Teams subagents, the Artifact tool, `~/.claude` config). Default to portable — a host-agnostic skill costs nothing extra, while one marked `true` is skipped entirely when converting for other tools. If the skill is host-specific, say which host in `compatibility` (e.g. `"Claude Code or any host with Bash"`).

### 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`.
- **Describe capabilities, not tool names.** Write "read the file", "run the
  command", "list the directory" — not "use the Read tool" or "use the Bash
  tool". Capability language keeps the same body working on every host (Claude
  Code, Hermes, DeepSeek, Copilot, Gemini CLI). Reserve tool names for genuinely
  host-specific instructions, and scope them ("on Claude Code, use the Task
  tool").

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:

```markdown
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)
- [ ] `requires_claude_code` is `false` unless the skill genuinely needs Claude-Code machinery (subagents, Artifact, `~/.claude`)
- [ ] Body uses capability language ("read the file"), not tool names ("use the Read tool")
- [ ] No Claude-Code-only references (plugin namespaces, `~/.claude` paths, `ANTHROPIC_BASE_URL`) unless scoped as host-specific

### 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.
- **Claude-Code-only assumptions** — Writing "use the Bash tool", hardcoding `~/.claude` paths, or assuming Agent Teams / the Artifact tool exist makes the skill bail on non-Claude hosts. Write capability language, default `requires_claude_code` to `false`, and scope any genuinely host-specific step.

## 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