---
name: skill-creator
description: "House guide for authoring plugin skills: creating a new skill, trimming or splitting a bloated one, writing or sharpening a description, and choosing between a skill, slash command, subagent, CLAUDE.md entry or MCP server. Covers the lean-index SKILL.md, progressive disclosure into bundled files, the reference vs workflow vs tool split, naming without a platform prefix, growing skills from observed failures, and the pre-ship audit. Ships templates, a checklist and description examples. Use for 'write a new skill', 'this skill is too long', 'improve this skill description', 'should this be a skill or an agent'. Not for writing the domain content itself, prompt writing unrelated to plugin skills, or per-session facts that belong in CLAUDE.md."
user-invocable: true
argument-hint: "[new | trim | description]"
allowed-tools: Read, Write, Edit, Glob
metadata:
  version: 1.0.0
  source: multi-agent-pipeline
---

# skill-creator - authoring plugin skills

> **Layer:** knowledge (reference). **Use when:** creating, trimming, splitting, naming or describing a plugin skill, or gating one before it ships.
> **Not for:** the domain content inside a skill (hand that to the domain skill), prompt writing unrelated to plugin skills, or facts every session needs (those go in CLAUDE.md).

Bundled, read when the step needs it:

- [template.md](template.md) - reference and workflow skeletons with frontmatter.
- [checklist.md](checklist.md) - the pre-ship checklist.
- [examples.md](examples.md) - weak and strong descriptions, wrong and right layer shapes.
- [audit.md](audit.md) - the multi-architect audit loop and its lens sets; driven by `scripts/audit-panel.js`.
- [label-check.md](label-check.md) - the fresh-subagent inference test for names and rule labels.

## Arguments

| Argument | Start at |
|---|---|
| `new` | Pick the artifact, write the description, then the template |
| `trim` | Leanness and the cut test, then the checklist |
| `description` | The description recipe and examples.md |

## Pick the artifact first

| Artifact | Holds |
|---|---|
| CLAUDE.md | facts and rules that are true in every session |
| Skill | a procedure or body of knowledge for a recurring task, loaded on demand |
| Subagent | work that needs its own reasoning, context window and tool set |
| MCP server | a structured integration with an external API |

## The description is the skill's only advertisement

Before a skill loads, the model sees its name and description and nothing else. Write the description before the body. It needs:

- **what** the skill covers or does, and **when** to use it;
- concrete **trigger phrases** a user would actually type, plus one sample request;
- the **platform** where it matters (iOS/SwiftUI, Compose, backend);
- an implied **boundary** against sibling skills;
- third person throughout.

Anthropic's measurements: a specific description instead of a vague one lifted activation from about 20% to about 50%; adding examples took it from about 72% to about 90%. A one-liner with no when, no triggers and no platform gives the router nothing to match. See examples.md.

## Keep SKILL.md an index

- Everything in SKILL.md sits in context for every turn after it loads. Aim for about one page; 500 lines is the hard ceiling.
- Push detail into bundled files **one level below** SKILL.md (reference, examples, scripts). They cost nothing until read. A file reached only through another bundled file tends to be read in part, so do not nest.
- Deterministic work belongs in a script. Running it keeps its source out of context; never ask the model to write that code again each time.
- **Cut test:** keep a line only if Claude would get the task wrong without it. Do not explain what the model already knows: a paragraph on how PDFs are structured loses to "use pdfplumber".

## Layer sets the degrees of freedom

| Layer | Voice | Contains | Never contains |
|---|---|---|---|
| reference | descriptive | invariants, conventions pointing at canonical files, decision heuristics, pitfalls, escape hatches | numbered procedures |
| workflow | imperative | numbered steps only for deterministic or irreversible actions (branch and PR, codegen, build and verify), citations of reference skills for judgement, a verification gate | open-ended judgement dressed as steps |
| tool | index | when to use, the run command, a sub-command overview; heavy detail in a bundled `reference.md`; the script is the engine | the engine's logic in prose |

`tools/figma-utility` in the iOS toolkit is the model tool skill.

## Naming

- No platform prefix: the toolkit name and the description already say it.
- Reference skills take an aspect noun (`navigation`); workflow skills a verb phrase (`branch-and-pr`).
- Avoid vague or reserved names: `helper`, `utils`, anything starting with `claude-`.
- When a name, title or strict-rule label has to carry its whole intent, run the label check before committing to it.

## Grow skills from failures

1. Do the task with no skill and note exactly where Claude goes wrong.
2. Write the smallest skill that fixes those failures. Nothing speculative.
3. Watch real use: promote detail that keeps getting read into SKILL.md, cut what is ignored, and sharpen the description whenever the skill failed to trigger.

## Before it ships

1. Run checklist.md as the self-review floor.
2. New or substantially changed skill: run the audit loop in audit.md until `clearsBar` is true.
3. Wire it: add the path to the `skills` array in `<plugin>/.claude-plugin/plugin.json`, bump the plugin version in `.github/plugin/marketplace.json`, and add a row to the plugin's `index` skill route table.
