Skill Builder

---
name: skill-builder
description: Creates a new Claude Code skill following best practices. Use when the user wants to build, create, write, or scaffold a new skill, slash command, or Claude Code plugin. Triggers on phrases like "build a skill", "create a skill", "new slash command", "add a skill", "scaffold a skill", "I want a skill that", "make a skill for". Always use this skill when skill authoring is the goal — even if the user doesn't say "skill" explicitly.
disable-model-invocation: true
argument-hint: [skill-name or description]
---

# Skill Builder

Scaffold and author a new Claude Code skill following best practices.

## Phase 1 — Gather Requirements

Ask (if not provided via `$ARGUMENTS`):
1. **What should this skill do?** (one-sentence description)
2. **Where should it live?**

   | Location | Path | Scope |
   |---|---|---|
   | Personal | `~/.claude/skills/<name>/` | All your projects |
   | Project | `.claude/skills/<name>/` | This project/team only |
   | Plugin | `<plugin>/skills/<name>/` | Where plugin is enabled |

   Priority when names conflict: enterprise > personal > project.

3. **How is it invoked?** User types `/skill-name`, Claude auto-invokes, or both
4. **Does it need supporting files?** References, examples, scripts, or asset templates

Don't proceed until intent is clear. Keep questions to 2–3 at a time.

Use answers to drive all subsequent decisions.

## Phase 2 — Determine Frontmatter

Choose frontmatter fields based on the skill's nature:

| Scenario | Frontmatter to use |
|---|---|
| Workflow with side effects (deploy, commit, send) | `disable-model-invocation: true` |
| Background knowledge only, no slash command needed | `user-invocable: false` |
| Read-only skill | `allowed-tools: Read, Grep, Glob` |
| Heavy research or exploration | `context: fork` + `agent: Explore` |
| User passes an argument | add `argument-hint: [what-it-accepts]` |

See [references/frontmatter-fields.md](references/frontmatter-fields.md) for the complete field reference.

## Phase 3 — Write the Description

The description is the **primary discovery mechanism**. Follow these rules:
- **Third person only**: "Processes X and returns Y" — never "I can help you…"
- **Include trigger phrases**: Concrete user phrasings that should load this skill
- **Be specific**: File types, domain terms, concrete scenarios
- **Be slightly pushy**: Push toward inclusion to combat Claude's undertriggering tendency
- **Max 1024 chars, no XML tags**

Draft the description before writing anything else. See [references/patterns.md](references/patterns.md) for good/bad examples and the pushy-description pattern.

## Phase 4 — Design the Skill Body

Structure the SKILL.md body using this hierarchy:

**In SKILL.md** (keep under 500 lines):
- Core concepts and essential procedures
- Workflow overview with checklists for multi-step flows
- Pointers to supporting files

**In references/** (detailed content):
- API docs, schemas, advanced patterns, troubleshooting
- Add a table of contents for files > 100 lines

**In examples/** (runnable code):
- Complete, copy-paste-ready examples

**In scripts/** (deterministic utilities):
- Executable helpers Claude runs without loading into context
- Must handle errors explicitly and document non-obvious constants

**In assets/** (templates):
- Boilerplate that appears verbatim in output

Always reference supporting files explicitly from SKILL.md — Claude won't discover them otherwise.

### Writing Style
- **Imperative/infinitive**: "Configure X", "Run Y", "Validate input"
- **Never second person**: Avoid "You should…", "You need to…"

## Phase 5 — Create the Files

1. Determine the skill directory path (personal or project-local)
2. Create the directory structure
3. Write `SKILL.md` with frontmatter + body
4. Write any `references/`, `examples/`, `scripts/`, or `assets/` files needed
5. Reference all supporting files from SKILL.md

## Phase 6 — Run the Shipping Checklist

Before finishing, verify every item in [references/checklist.md](references/checklist.md).

Report which items pass and flag any that need attention. Fix any failures before declaring the skill complete.

**If skill doesn't trigger**: Make description more specific with clearer trigger phrases.
**If skill triggers too often**: Narrow description or add `disable-model-invocation: true`.
**If skill is excluded from context**: Run `/context` to check — descriptions compete for a 2% context window budget (~16,000 chars). Shorten the description or set `SLASH_COMMAND_TOOL_CHAR_BUDGET` to increase the limit.

## Naming Conventions

- Lowercase, hyphens only, max 64 chars
- Prefer gerund form: `processing-pdfs`, `analyzing-spreadsheets`
- Acceptable: noun phrases (`pdf-processing`) or action verbs (`process-pdfs`)
- Avoid: `helper`, `utils`, `tools`, `data`, anything with `anthropic` or `claude`

## String Substitutions Available in Skills

| Variable | Meaning |
|---|---|
| `$ARGUMENTS` | All text after the skill name |
| `$ARGUMENTS[N]` | Nth argument (0-indexed) |
| `$N` | Shorthand for `$ARGUMENTS[N]` |
| `${CLAUDE_SESSION_ID}` | Current session ID |

## Additional Resources

- Advanced patterns (subagents, dynamic context, visual output, etc.): [references/patterns.md](references/patterns.md)
- Complete frontmatter field docs: [references/frontmatter-fields.md](references/frontmatter-fields.md)
- Shipping checklist: [references/checklist.md](references/checklist.md)