skill-creator

skill-builder — Skills That Don't Rot

Takes a plain-language description of a task and produces a ready-to-ship agent skill. The design goal is skills that are cheap in ambient context and current with the skill spec — most skill generators fail on exactly those two axes: they don't know about arguments/argument-hint, never suggest disable-model-invocation, and write bloated descriptions that tax every session.

Modes

Parse $ARGUMENTS for a mode; default to new when the input is a description.

• new <description> — scaffold a skill from scratch (the flow below).
• review <path> — audit an existing SKILL.md against steps 1–3's decision points and run the validator (step 4). Report findings; don't rewrite unless asked.
• migrate <path> — convert a legacy .claude/commands/*.md file into a skill directory: carry the frontmatter over, apply the review checklist, and place supporting content in the directory.

Before You Start

Read references/claude-code-frontmatter.md — a pinned, dated snapshot of the skill frontmatter spec, argument substitutions, and context-loading behavior.

Staleness policy: if the snapshot date is more than 3 months old, warn the user and continue with the pinned snapshot. Do not re-fetch or modify the reference mid-generation — updating the spec is a maintenance operation (agent-skill-builder's spec-drift CI watches for it), not a side effect of building a skill. Only update the snapshot when the user explicitly asks.

Also read the host repo's CLAUDE.md and existing skills — avoid duplicating a skill that already exists, and match local conventions.

Instructions

1. Clarify the skill

Ask (or infer from context):

• Target runtime: Claude Code (default — full frontmatter feature set) or the portable Agent Skills core (name + description only; keep Claude-specific fields out or document them as optional extensions).
• Name: lowercase, hyphenated. In Claude Code the directory name under .claude/skills/ is the command you type; frontmatter name is only a display label.
• Who invokes it — the most important design decision:
  • User-only (side effects, or timing the user controls: publish, send, deploy, log) → disable-model-invocation: true. Bonus: the description is then not loaded into every session — zero ambient context cost.
  • Claude-only (background knowledge, not an action) → user-invocable: false.
  • Both (default) → the description must carry the trigger keywords, and it becomes a permanent per-session context cost. Make it earn that.
• Arguments: does the user pass input on the command line? If yes: set argument-hint, and consume $ARGUMENTS (or $0/$1, or named arguments:) in the body. Don't make the model guess what the trailing text means.
• Input/Output: what does it read (files, MCP data, live command output), what does it produce?
• Tools: allowed-tools is a pre-approval grant (no permission prompts while active), not a restriction — scope entries tightly, e.g. Bash(git add *) not Bash. Use disallowed-tools to actually remove tools.
• Where it runs: inline (default — shares conversation context) or context: fork + agent: for isolated, self-contained tasks. Fork only works when the body is an explicit task, not reference guidelines.
• Data at load time: use dynamic context injection (!`command` at line start) to inline live data (a diff, a status file) before the model reads the skill.
• Only set model/effort overrides with a specific reason. Use paths: for skills scoped to certain files.