skill-creator v1.1.0A

Immutable. This exact content is served forever at /api/v1/blob/03b3ccd87d57365c.

---
name: skill-creator
description: "Authors the CONTENT of a brand-new agent skill for any stack or agent runtime - turns a vague capability request into a routable SKILL.md with a trigger-rich description, hard rules, and a verification loop, and repairs a skill that never activates. Activates when the user says 'create a skill', 'write a skill for X', 'make this a skill', 'turn this into a skill', 'my skill never triggers', 'why doesn't my skill activate', or asks to extract a repeated workflow into something reusable. Owns authoring and routing repair; defers to vd:skill-management for scaffolding, vendoring, versioning and release mechanics, vd:skill-evolve for improving skills that already exist, vd:skill-audit for usage statistics, and vd:rule-miner for standing CLAUDE.md rules."
license: MIT
argument-hint: "[capability | --audit <name> | --extract] [--dir <skills-root>]"
metadata:
  author: vanducng
  version: "1.1.0"
---

# Skill Creator

> A skill is a **conditional prompt fragment**. It costs context every time it loads and earns its place only by making the agent behave better than the base model would.

Boundaries: authoring something new is this skill; improving what already ships is `vd:skill-evolve`; scaffolding, vendoring, and releases are `vd:skill-management`; usage stats are `vd:skill-audit`. `vd:skill-management --create` hands authoring here - if it picked up the request first, continue rather than bouncing it back, then return to it for the catalog mechanics. Skills instruct an **agent**; docs inform a **human** - if the reader is a person, write docs instead.

## The bar: does this deserve to be a skill?

Answer all four **yes** before writing anything.

1. **Recurrence** - will this be needed again, in a form worth reusing? A one-off belongs in the conversation.
2. **Non-obvious** - does it encode judgement, house rules, or a gotcha the base model gets wrong unaided? Restating `git commit -m` teaches nothing.
3. **Routable** - can you name the concrete phrases a user types when they want it? If you can't write the trigger list, the agent can't match it.
4. **Bounded** - is the domain narrow enough for firm rules? "Be a good engineer" is not a skill.

Fail any → say so and stop. **Not writing a skill is a valid, common outcome.** A catalog of 20 sharp skills beats 80 vague ones: every extra skill dilutes routing and taxes context.

## Hard rules

1. **Description is the router.** It is the *only* thing an agent sees when deciding whether to load the skill. It must state what the skill does AND the trigger phrases. Vague descriptions never fire - a perfect body behind a weak description is dead weight.
2. **Verify before claiming done.** Run the repo's validator and confirm the skill actually loads. "Wrote the file" is not "shipped."
3. **Prescribe, don't describe.** "Run X, then verify Y" beats "this skill is about X." Every section should change what the agent *does*.
4. **Portable by default.** No personal absolute paths, usernames, machine-specific locations, or assumed OS. Use `$HOME`, repo-relative paths, env vars, or documented overrides. A skill that only works on the author's laptop is broken.
5. **Earn every line.** Long skills get skimmed and their rules get dropped. Cut anything the base model already does correctly. The bar lives in [`references/writing-principles.md`](references/writing-principles.md) (two loads, no-op test, completion criteria, anti-staleness, length tracks failure risk, rationalizations to catch).
6. **Name the runtime seams.** If a step depends on tooling that isn't universal (a specific CLI, an editor API, a subagent mechanism), say so and give the fallback.

## Workflow

### 1. Interrogate the request

Never write from a one-line prompt. Establish, asking the user when unclear:

- **Trigger phrases** - the literal words a user would type. Collect 4-8.
- **Concrete task** - one real example end to end, with the expected output.
- **Failure mode without the skill** - what does the agent get wrong today? This becomes the hard rules. *If nothing goes wrong today, the skill is unnecessary.*
- **Scope edges** - what is explicitly NOT this skill's job, and which skill owns that instead.
- **Verification** - how does anyone know the skill worked?

Can't answer "what goes wrong without it?" → return to the bar above.

### 2. Locate the target and learn local convention

Skill roots differ by agent and project. Detect rather than assume, and **resolve in this order** - a project-local root always wins over a global one, so the skill lands where the user is working:

1. explicit `--dir <path>`
2. a root declared by the repo (`AGENTS.md`, `CONTRIBUTING.md`, a manifest)
3. project-local: `./skills`, `./.agents/skills`, `./.claude/skills`
4. runtime-global fallbacks: `$HOME/.factory/skills`, `$HOME/.claude/skills`, `$HOME/.agents/skills`

If several candidates exist at the *same* precedence level, **ask** rather than guess - writing a project skill into a global root (or the reverse) is silently wrong and hard to notice later.

If the root is a git repo or ships helper scripts, **its conventions win over this skill's defaults**:

```bash
ls scripts/ 2>/dev/null                      # new-skill.sh, validate.sh, check-*.sh
```

Read any `AGENTS.md` / `CONTRIBUTING.md` / `CLAUDE.md` at that root **in full** - naming, privacy, validation, and catalog-sync rules are often stated far down the file, and a missed one fails the repo's own gates.

Read 2-3 existing skills in that root and match their frontmatter fields, heading depth, and voice. A skill that looks foreign to its catalog is harder to trust and maintain. Prefer a provided scaffold (`scripts/new-skill.sh <name>`) over hand-creating the directory.

### 3. Write the description (highest-leverage step)

Spend real effort here - it decides whether the skill ever runs.

**Shape:** `<what it does + for what stack/context> + Activates when <situations>, <file/path signals>, or when the user says '<phrase>', '<phrase>'.`

| | Example | Why |
|---|---|---|
| Bad | `"Helps with testing."` | No trigger, no scope. Never routes. |
| Bad | `"The best skill for all your database needs!"` | Marketing, not matching. |
| Good | `"Writes and fixes Pest tests in Laravel repos. Activates when editing tests/**, when a test fails after a code change, or when the user says 'write a test', 'fix the failing test', 'add coverage'."` | Names stack, file signal, and literal phrases. |

Rules:
- Third person, declarative. No "you" or "I".
- Include the **stack or domain** so it doesn't collide with sibling skills.
- Include **negative scope** when a neighbour is easily confused: `"Do not use for <X> - that's <other-skill>."`
- Quote trigger phrases verbatim as users type them, not as you'd phrase them.
- Keep `description` at or under 1024 characters. Pi and Claude Code reject longer frontmatter and skip the skill.

### 4. Write the body

Default skeleton - drop any section that would be filler:

```markdown
# <Name>

> One-line framing of the discipline.

## What this skill is - and isn't      # boundary table vs neighbours
## Hard rules                          # numbered, non-negotiable, each with a WHY
## Workflow                            # numbered steps, each with a verification
## <Domain reference>                   # tables/rubrics the agent applies
## Anti-patterns                        # concrete failure modes to avoid
```

Guidance:
- **Tables over prose** for anything with cases. Agents apply them more reliably.
- **Every hard rule needs a reason.** Unjustified rules get rationalized away under pressure.
- **Include the failure mode, not just the instruction.** "Run the validator (a malformed frontmatter block silently disables the skill)" beats "run the validator."
- **Show one worked example** when the output shape matters.
- Keep the core under ~200 lines; push depth into `references/<topic>.md` and link it. Long context degrades rule-following.
- Add `scripts/` only for deterministic mechanics (validation, scaffolding) - never to wrap something the agent should reason about.

### 5. Verify - the step that gets skipped

Do not report success on file creation alone.

Run the repo's validator if one exists, and **let it fail loudly** - never mask the exit status with `|| true`, or a broken skill reports as shipped:

```bash
if [ -f scripts/validate.sh ]; then bash scripts/validate.sh; fi   # non-zero exit = do not ship
```

Then check by hand, since validators typically lint frontmatter and nothing else:

- [ ] Frontmatter parses; `name` is kebab-case and **equals the directory name** (a mismatch silently disables the skill in most loaders).
- [ ] `description` names both the capability and the trigger phrases, and is ≤ 1024 characters.
- [ ] No personal paths anywhere in the skill, not just `SKILL.md`:
      `grep -rnE '/Users/[a-z]|/home/[a-z]|C:\\Users' <skill-dir>/`
- [ ] Every referenced file actually **resolves** - extracting the names is not enough, test each one:
      ```bash
      grep -rhoE '(references|scripts|assets)/[A-Za-z0-9._/-]+' <skill-dir>/ | sort -u |
        while read -r f; do [ -e "<skill-dir>/$f" ] || echo "MISSING: $f"; done
      ```
- [ ] Repo-specific gates pass (docs sync, path guards, catalog counts) - see the root's `AGENTS.md`.
- [ ] **Routing rehearsal**: read the description cold and ask *"would I load this for each trigger phrase, and NOT load it for a neighbour's task?"* Both directions matter - a description that over-triggers is as bad as one that never fires. Where the runtime can dry-run skill matching, use it; otherwise say routing is unverified rather than implying it was tested.

Ship only when all pass.

### 6. Sync the catalog

Many skill roots track a catalog, count, or index. A skill added without its catalog entry is invisible and counts as incomplete. Check the root's `AGENTS.md` for the required files and any `check-docs-*.sh` gate, then update them in the same change.

## `--audit <name>`: fix a skill that never fires

Diagnose in this order - the earliest failure wins, and it is almost always the description.

| Symptom | Likely cause | Fix |
|---|---|---|
| Never activates | Description lacks trigger phrases | Rewrite per §3 with literal user wording |
| Activates for the wrong tasks | Description too broad, or overlaps a sibling | Narrow scope; add explicit negative scope |
| Activates but ignored | Body is descriptive, not prescriptive | Convert prose to numbered rules + workflow |
| Rules dropped mid-task | Skill too long, or rules unjustified | Cut to essentials; attach a WHY to each rule |
| Works only for the author | Hardcoded paths or assumed local tooling | Parameterize; document the override |
| Loader rejects it | `name` ≠ directory, malformed frontmatter | Run the validator; fix frontmatter |

Report findings by severity, fix them, then re-run §5.

## `--extract`: turn a repeated conversation into a skill

When the user says *"we keep doing this"*: reconstruct the actual steps taken (don't idealize them), identify the corrections made along the way - those become hard rules - then apply §1's bar. Frequency alone doesn't justify a skill; frequency **plus** a non-obvious failure mode does.

## Anti-patterns

- **Kitchen-sink scope.** "backend-development" covering HTTP, DB, queues, and deploys can't hold firm rules. Split by decision boundary.
- **Copy-paste cargo cult.** Cloning another skill's headings when half don't apply. Structure serves content.
- **Silent overwrite.** Creating a skill whose name already exists, clobbering the original. Always check first.
- **Documentation cosplay.** Explaining a domain instead of directing an agent. Skills change behavior.