skill-builder

Files (3)

• SKILL.md
• reference.md
• smart-skill-ref.md

SKILL.md (first lines)

## What This Skill Does

Guides the creation and optimization of Claude Code skills using official best practices. Use this whenever:

- Building a new skill from scratch
- Optimizing or auditing an existing skill
- Deciding on advanced features (subagent execution, hooks, dynamic context, etc.)
- Troubleshooting a skill that isn't working correctly

For the complete technical reference on all frontmatter fields, advanced patterns, and troubleshooting, see [reference.md](reference.md).

## Skill Naming & Families

Skills are organized into **families** by naming convention. This is how related skills stay legible in a flat directory. Apply it to every new skill and every audit.

**Core fact:** for personal/project skills the **directory name IS the `/command`**. Frontmatter `name:` is only a display label and must be lowercase-hyphen with **no leading hyphen** — so for orphan skills the dir and `name:` intentionally differ.

**The four roles:**

| Role | Pattern | Example | `disable-model-invocation` | Notes |
|---|---|---|---|---|
| **Meta** (orchestrator) | plain name | `importer`, `categorize`, `organizer` | unset (auto-invocable) | Owns a pipeline/family; coordinates children via the Skill tool. |
| **Child** | `<meta>-<child>` | `categorize-venue`, `importer-audit` | **unset — leave it OFF** | Worker owned by a meta. MUST stay model-invocable or its meta can't delegate to it via the Skill tool. Add `context: fork` if it must run isolated. Control triggering with a narrow description, not a flag. |
| **Sub-family** | `<meta>-<meta>-<child>` | `importer-audit-schema` | **unset — leave it OFF** | Use only when a child is itself a meta with its own workers. Prefix chains left→right, most-general first. Cap at 3 tiers — deeper means it should become its own top-level meta. |
| **Orphan** | `-<child>` (leading hyphen) | `-renamer` → `/-renamer` | usually unset | "Hasn't found a home / baggage." A standalone or not-yet-classified worker. Dir leads with `-`; `name:` stays hyphen-free (`name: renamer`). Set `true` ONLY if nothing delegates to it and it's user-only (destructive/expensive). |

**Rules:**

1. **A family prefix requires an existing meta of that exact dir name.** `categorize-*` is only valid if a `categorize` meta exists.
2. **Do NOT set `disable-model-invocation: true` on a child (or any skill a meta delegates to).** That flag blocks the **Skill tool entirely** — not just auto-triggering — so a meta calling `Skill(categorize-linker)` fails with *"cannot be used with Skill tool due to disable-model-invocation."* There is no flag for "delegatable but won't auto-fire," because Skill-tool delegation *is* model invocation. Keep the flag OFF and control unwanted triggering with a **narrow, distinct description**. Reserve `disable-model-invocation: true` for user-only standalones that no meta delegates to (typically destructive/expensive, meant to be typed by the user).
3. **Orphans keep a normal (hyphen-free) `name:` field.** Accept the dir≠name mismatch — that mismatch is the *signal* the skill is unhomed. When an orphan is adopted, rename `-renamer` → `<meta>-renamer` (see rule 6).
4. **Grouping is naming-only.** Discovery is a flat scan of each `.claude/skills/` root; prefixes do NOT nest folders and a child folder inside a meta folder is NOT discovered.
5. **Descriptions carry routing.** Meta description = whole-goal triggers; child description = narrow sub-task with distinct terms so it won't collide with its meta.
6. **Renames use `git mv`** (preserve history) and rewire every `/command` reference — skill bodies, `CLAUDE.md`, `oracle.md` — in one commit. Leave historical logs (e.g. `.claude/iterate/archive/`) untouched.

**Decide the role for any skill:** Does it orchestrate others? → **meta** (plain name). Is it owned by/triggered as a stage of a meta? → **child** (`<meta>-<child>`, `disable-model-invocation` left OFF so the meta can delegate). Is that child big enough to own its own workers? → **sub-family** (`<meta>-<meta>-<child>`). None of the above / undecided? → **orphan** (`-<child>`) until it finds a home.

## Description Budget (routing economics)

Descriptions are the only part of a skill loaded at startup, so they are a shared, finite resource. Two separate limits apply, and both fail **silently** — nothing warns you:

| Limit | Value | What happens when exceeded |
|---|---|---|
| **Per skill** | 1,536 chars for `description` + `when_to_use` **combined** | Truncated mid-sentence in the skill listing. Trigger phrases past the cut are invisible to routing. |
| **All skills** | 2% of the context window (fallback 16,000 chars) | Skills beyond the budget stop being listed at all — they can't auto-fire. |

### Know the target's failure mode before you ship

A budget is not advice. Before shipping a skill to any runtime, know what that
runtime does when you exceed its cap, because the answer decides whether the cap
is a guideline or a gate:

| Failure mode | What it means | How to treat the cap |
|---|---|---|
| **Truncates** | The tail is silently cut. Trigger phrases past the cut stop existing, and nothing says so. | **Hard gate.** Verify with real numbers and refuse to ship over. |
| **Drops whole entries** | Skills past the budget stop being listed at all. | Hard gate for anything that must route. |
| **Degrades gracefully / no cap** | Over-length costs context, not correctness. | Going over is a judgment call, not a defect. |

**Both of these runtimes shorten before they drop.** Claude Code truncates a
description past 1,536 mid-sentence; Codex shortens descriptions first when the
manifest overflows and omits whole skills only under severe overcrowding — the
one case that warns. Either way the tail goes, and the tail is where the
least-common trigger phrases live, so the loss is silent in the way that matters:
routing quietly gets worse and nothing says so.

**Both budgets are 2% of the context window**, with a fixed fallback when that
window is unknown — 16,000 for Claude Code, 8,000 for Codex. The fallback is the
worst case, so build against it.

**No safety margins.** A margin is unused capacity that hides the real rule: if
the limit is 8,000 then 8,000 is fine and 8,001 is not, and a build that holds
back to 7,600 is just failing 400 chars early while still not enforcing
anything. Set the number to the actual limit and **enforce it in the tool** —
Codex's porter (`skills/skill-2-codex/scripts/`) validates every generated port
and exits non-zero rather than installing one that is broken or over cap.

**Frontmatter must be valid YAML, not merely parseable by today's parser.** A
description opening with a YAML indicator (`*`, `&`, `>`, `|`, `!`, `%`, `` ` ``)
is a different node type, not text — `description: **Always invoke...` reads as
an alias and fails to load. Claude Code tolerates it; Codex does not. Quote the
value. Confirmed live: two skills failed to load in Codex and nineteen more were
one strict parser away from the same fate.

Four facts that change how you write frontmatter:

1. **Omitting `description` does not save budget.** If absent, the listing falls back to the *first paragraph of the markdown body* — usually longer and not routing-optimized. To spend less, write a *shorter* description, never no description.
2. **`disable-model-invocation: true` skills cost zero budget.** Claude can't route to them, so their descriptions aren't loaded. They also don't appear in `/context`'s skill list — that absence is expected, not a bug.
3. **`when_to_use` shares the same 1,536 cap.** It's the right home for a long trigger-phrase inventory, keeping `description` a clean one-or-two-sentence statement of what the skill does. Splitting improves readability; it does **not** buy extra room.
4. **Put the key use case first.** Truncation takes the tail, so whatever routes most often must appear early.

### Family convention: triggers live in the meta

For a meta + children family, concentrate routing in the meta and keep children short:

- **Meta description** carries the whole family's trigger phrases — every phrase that should reach *any* child. It is the family's front door.
- **Child descriptions** stay to roughly one line (~60–150 chars): what this child does, in terms distinct from its siblings. Children are reached through the meta's `Skill()` call or by explicit `/command`, and **neither path needs a loaded description** — the Skill tool takes a name, not a description.

This keeps N children from each spending a full description's worth of a shared budget to advertise a door the user is meant to enter through the meta. It also matches the routing you want: "prune the tests" should reach `/testmaster`, which then decides it means `testmaster-prune`.

**Check it with real numbers, never by eye** — count `description` + `when_to_use` per skill against 1,536, sum across all model-invocable skills against 16,000, and run `/context` to confirm nothing is being dropped.

## Quick Start: What Is a Skill?

A skill is a reusable set of instructions that tells Claude Code how to handle a specific task. Skills live in `.claude/skills/[skill-name]/SKILL.md` inside your project. When you type `/skill-name` or describe what you need in natural language, Claude loads the skill's instructions and follows them.

Think of skills as SOPs for Claude. Instead of re-explaining a workflow every conversation, you write it once and invoke it forever.

**How they work under the hood:**
- Your project's `CLAUDE.md` instructions are always loaded, every conversation
- Skill *descriptions* (from frontmatter) are loaded at startup so Claude knows what's available — but only for model-invocable skills, and only up to the budget (see "Description Budget" above)
- The full skill content only loads when the skill is actually invoked
- Once loaded, Claude follows the skill's instructions while still respecting your CLAUDE.md rules

---

## Mode 1: Build a New Skill

When building a new skill, run the **Discovery Interview** first. Do NOT start writing files until discovery is complete.

From x85446/claudecodetricks, MIT.

More from x85446/claudecodetricks