skill-creator

name	skill-creator
description	Authors and audits Claude Code skills, covering `SKILL.md` frontmatter, directory layout, scope (project, user, plugin, managed), invocation control, and bundled `references/` or `scripts/`. Use when a skill is being written or edited, when a recurring playbook is being captured, when `allowed-tools` or `paths:` need choosing, or when a skill fails to fire. Triggers on "create a skill", "write a SKILL.md", "turn this into a skill", "package this workflow", "skill not triggering", "skillify". Use even when the user never says "skill" but is capturing a procedure they keep retyping. Pair with `ac:prompt-writer` for the body text.
when_to_use	Creating, editing, auditing, or debugging any Claude Code skill at any scope.

Skill Creator

You are about to write or edit a skill another Claude will load. A skill is a directory with a SKILL.md. Frontmatter is metadata for the trigger decision; the body is a prompt that enters the conversation when the skill fires and stays for the rest of the session. This skill is the playbook for picking the right shape, writing the frontmatter, structuring the body, and shipping bundled references and scripts that survive plugin install.

Target is Opus 5. Same rules work for Sonnet 5 at lower cost and for Haiku 4.5, which supports no effort parameter at all. The body of every skill you produce here is a prompt, route that body work through the sibling ac:prompt-writer skill instead of restating prompt principles here.

Two jobs, not one

Writing a skill splits cleanly into two tasks, and conflating them is the most common authoring mistake.

1. Skill shape. Frontmatter, file layout, scope, invocation control, bundling. This file teaches that.
2. Body content. The markdown the model reads when the skill triggers. This is a prompt. Route through ac:prompt-writer (architecture, snippets, anti-patterns, Opus 5 tuning).

The shape decisions front-load most of the leverage. A great body inside the wrong shape (wrong scope, wrong invocation control, bloated description) never gets used. A modest body inside the right shape gets used every day.

Decision flow

Route by the user's request. Each branch lands on the right reference for the depth.

Is a skill the right tool at all?
├── Single fact that never changes → CLAUDE.md, route through `ac:claude-md-rules-creator`. Not a skill.
├── Truly one-off task → just do it. Not a skill.
├── Determinism that the body cannot guarantee → hook, not skill. Route through `update-config`.
├── Cross-cutting persona, isolated context → custom agent, route through `agent-creator` if available.
└── Recurring playbook, procedure, or knowledge → SKILL is the right tool, continue.

Is it user-driven `/name [args]` with arguments, often `disable-model-invocation: true`?
├── YES → use this skill for shape, then specialize through `command-creator` if available
│         (argument design, shell injection, built-in command patterns).
└── NO  → continue with this skill alone.

Is this an audit or fix of an existing skill?
├── YES → `${CLAUDE_SKILL_DIR}/references/anti-patterns.md` first, then
│         `${CLAUDE_SKILL_DIR}/references/claude-code-mechanics.md` if behavior is unclear.
└── NO  → walk the Workflow below.

When the path runs through command-creator, agent-creator, or ac:claude-md-rules-creator, do both: invoke the matching creator for shape (if it is available in the session), keep this skill loaded for the parts that are still skill-shaped.

Core principles

Eight rules that change outcomes the most. Detail in the references.

1. Concise is the contract. The body shares the context window with the system prompt, every other invoked skill, the conversation, and the user's actual request. Default to "Claude is already smart", only add what it would not know without you. Challenge each paragraph against "does this justify its tokens?"

2. Match freedom to fragility. Three settings: high freedom (text instructions, multiple valid paths, code review, exploration), medium freedom (parameterized scripts with a preferred pattern, report generation), low freedom (specific commands, fixed sequences, migrations, deploys). Over-constraining open fields wastes tokens; under-constraining narrow bridges breaks production.

3. The description is the selection mechanism. When the model has 100+ skills available, it picks based on description alone. Front-load the verb and noun, write third person ("Processes Excel files"), include trigger phrases, cover synonyms, be a little pushy. Modern Claude undertriggers skills, so lean toward catching the request.

4. Progressive disclosure is the structural superpower. Metadata always loaded, body on trigger, references/ and scripts/ only when the body points at them. Use this: keep the body lean, push detail into one-level-deep references, anchor each with "read this when X". Two-level-deep references suffer because the model often previews intermediate files with head -100.

5. Standing instructions, not turn-scoped phrasing. The body enters the conversation as a single message and stays for the rest of the session. Claude does not re-read SKILL.md. "Always use the bundled script" lasts; "for this turn, use the bundled script" rots by turn three.

6. State scope explicitly, in both directions. Write "apply to every step, not just the first" when a rule must hold throughout. Also name the upper bound: Opus 5 can widen a task's scope on its own and re-verify finished work, so a body that declares what the skill does NOT touch holds its shape better than one that only declares what it does.

7. No aggressive caps. "CRITICAL", "you MUST", "ALWAYS" in modern Claude produce weird compliance behaviors and overtriggering. Plain instructions work; if a rule needs weight, explain the why.

8. The colleague test. Re-read the body as if you had never seen the conversation. If a fresh reader would be confused, the model will be too.

Where skills live

Scope	Path	Reach	Default for
Managed	enterprise managed dir	All users in the org. Highest precedence.	Org-wide policy and compliance
User	~/.claude/skills/<name>/SKILL.md	All projects on this machine.	Cross-repo personal workflows
Project	.claude/skills/<name>/SKILL.md (walks up from cwd)	This repo only. Commit to share.	Repo-specific workflows
Plugin	<plugin>/skills/<name>/SKILL.md	Wherever the plugin is installed. Auto-namespaced as plugin:skill.	Distributing to others

Precedence is managed > user > project; plugin skills live in their own namespace and never collide. Plugin skills must reference bundled files via the skill-directory token, never via repo-relative paths, because the install destination is unknown at author time. The token resolves to the skill's subdirectory inside the plugin, not the plugin root. See Anthropic docs for the full substitution table.

Frontmatter is minimal by default

The only fields a working skill needs are name and description. when_to_use is optional but usually worth adding. Everything else is opt-in: each optional field exists because some skills hit a specific condition that requires it. Add a field only when you can name the condition; otherwise leave it out and let the default behavior apply.

Field	Required?	Default	Add when...
name	recommended (falls back to directory)	directory name	almost always; only omit when the directory name is already the right slug
description	recommended	first paragraph of body (usually wrong)	always
when_to_use	optional	empty	the description is busy and trigger phrases need a separate slot; usually worth setting
argument-hint	optional	none	the skill takes positional arguments and you want autocomplete to hint at them
arguments	optional	none	the skill takes input and you want named-positional substitutions ($pr_number instead of $0)
disable-model-invocation	optional	false	the skill has irreversible side effects (/deploy, /commit, /send-slack); user must trigger explicitly
user-invocable	optional	true	the skill is background reference knowledge that has no meaningful slash-menu invocation
allowed-tools	optional	none (every tool call goes through normal permissions)	the body issues specific tool calls you want pre-approved to avoid prompting (narrow patterns only)
context	optional	inline	the work is bounded, self-contained, and benefits from running in an isolated subagent context
agent	optional (only meaningful with context: fork)	general-purpose	a different subagent type (Explore, Plan, custom) fits the task better
paths	optional	none (skill always discoverable)	the skill is relevant only to a subset of files; you want to keep the description out of unrelated sessions' budget
model	optional	inherit session model	the skill needs a heavier or lighter model than the session default
effort	optional	inherit session effort	the skill needs more or less reasoning budget than the session default
hooks	optional	none	the skill needs deterministic enforcement that body instructions cannot guarantee (logging, gating destructive commands)
shell	optional	bash	the skill runs PowerShell on Windows
version	optional	none	you want your own bookkeeping

Anti-pattern: copying every optional field from a template into a new skill "just in case". Each unused field adds noise without behavior. A reference skill with conventions for your codebase usually needs just name + description + when_to_use. A simple task skill adds argument-hint + arguments and that is often enough. Reach further into the table only when the skill's specific behavior demands it.

Escape convention used in this documentation. This SKILL.md is itself a skill body that the Claude Code loader preprocesses. Any literal full-arguments token, skill-directory token, or session-id token (a plain dollar sign followed by the placeholder name) written here would be substituted by the loader on every invocation, corrupting the documentation. To prevent that, the docs below render those tokens with the HTML entity $ standing in for the dollar sign: you read $ARGUMENTS, the loader sees $ARGUMENTS and skips substitution, the model interprets the entity as $ and reads the intended token. In your own skill bodies, drop the entity and write a plain dollar sign.

Who invokes it

The default works for most skills: both the user (via /name) and the model (via auto-load) can invoke. Override only when there is a specific reason.

Frontmatter	User can /name	Model auto-loads	Add when...
(defaults)	yes	yes	most skills, including all reference content and most workflow skills
disable-model-invocation: true	yes	no	the skill has irreversible side effects (/deploy, /commit, /send-slack); you do not want the model deciding to fire it
user-invocable: false	no	yes	the skill is background reference knowledge (a legacy-billing-context skill) where typing /legacy-billing-context is not a meaningful action
both	no	no	rare: a hidden helper activated only via paths: or by another skill referencing it

Inline or forked

Inline is the default and the right choice for most skills. Set context: fork only when the work is bounded, the body is an actionable task, and you do not need the user to steer mid-process.

Decision	Inline (default, most skills)	Forked (context: fork, opt-in)
Conversation history	Available	Not available
User can steer mid-process	Yes	No
Body shape allowed	Reference content or task	Actionable task only
Main context cleanup	No	Yes, work happens in an isolated context
agent: field	Ignored (do not set)	Picks subagent type (Explore, Plan, general-purpose, or any .claude/agents/<name>.md); only set when forking

Reference content in a forked skill produces a subagent with guidelines but no goal, returning nothing useful. If the body has no actionable task, leave the default inline.

Arguments

Skip this section if the skill takes no input from the user. Most reference skills (conventions, style guides) and many task skills (audits that operate on session state) need no arguments at all.

Set arguments: and argument-hint: only when the skill genuinely takes input (a PR number to cherry-pick, a topic to research, a path to extract from). The loader substitutes tokens at injection time, before the model sees the text. Per the escape convention above, the docs show tokens with $; in your skill body, write a plain dollar sign.

Token	Resolves to
$ARGUMENTS	full argument string as the user typed it
$ARGUMENTS[N] or $N	Nth positional, shell-quoted, 0-indexed
&#36;<name>	named argument from the arguments: frontmatter list
&#36;{CLAUDE_SKILL_DIR}	absolute path to this skill's directory
&#36;{CLAUDE_SESSION_ID}	current session id
&#36;{CLAUDE_EFFORT}	active effort level (low/medium/high/xhigh/max)

Full table with examples and parsing pitfalls: ${CLAUDE_SKILL_DIR}/references/frontmatter.md.

Set argument-hint: so autocomplete reflects the expected shape. If the body has no full-argument token and the user passed arguments, the loader appends ARGUMENTS: <input> automatically; treat that as a fallback, not a design.

Pre-approving tools

Skip this section if the skill's tool calls already work without prompting in the user's normal permission flow. Most reference skills (no shell commands) and skills that only Read or Grep on already-permitted paths do not need allowed-tools: at all.

Set allowed-tools: only when the body issues specific tool calls that would otherwise prompt the user repeatedly during the run (a workflow that fires gh pr view, git add, git commit in sequence). It is friction reduction, not a security boundary. The user's deny rules still apply.

When you do set it, list narrow patterns matching the calls the body actually issues:

• Good: Bash(gh pr view:*), Bash(git add:*) Bash(git commit:*), Read Grep Glob
• Bad: Bash (whitelists every shell command, defeats the permission system), * (defeats the field entirely)

Read the body, enumerate every tool call it actually makes, list exactly those.

Conditional activation

Skip paths: for most skills. The default (no paths:) means the skill is discoverable from session start, which is what you want when the skill applies broadly.

Set paths: only when the skill is genuinely relevant to a subset of files in a polyglot or monorepo setup (a flutter-conventions skill in a repo that also has a Rust backend; a database-migrations skill scoped to db/migrations/**). The glob list (gitignore syntax, comma string or YAML list) defers the skill from the description listing until the model touches a matching file, which keeps the description budget free for sessions that never need it.

Bundled files

Need	Put it in
Detailed reference docs the body points to	references/<topic>.md
Scripts the body runs via Bash	scripts/<name>.<ext>
Templates, fonts, icons used in output	assets/<name>

Reference them explicitly from the body, anchored to a trigger (the block below uses HTML entity $ for $ to avoid self-substitution; in your skill body, write the plain literal):

For full schema details, read `${CLAUDE_SKILL_DIR}/references/api-schema.md`.
Run `python ${CLAUDE_SKILL_DIR}/scripts/build_chart.py "$ARGUMENTS"` to render the chart.

Relative paths break when the skill is invoked from a different cwd. ${CLAUDE_SKILL_DIR} is the only portable form. For plugin skills, it is the only form that survives install.

Workflow

Walk these in order. Each step assumes the previous resolved.

1. Capture intent

If the conversation already shows a workflow the user wants captured (corrections, tool sequence, edits to the format), extract from history. Otherwise ask in tight rounds via AskUserQuestion, not all at once.

Always-needed questions:

• What does the skill do, in one sentence?
• When should the model load it (trigger phrases, file types, user requests)?
• Project, user, or plugin scope?

Conditional questions (ask only when the answer to an always-needed question implies the skill needs the field):

• Inline or forked? Ask only if the work sounds bounded and self-contained (a research task, an audit). Default is inline for everything else.
• User-only vs both? Ask only if the skill has irreversible side effects (deploy, commit, send-message).
• Arguments? Ask only if the user implied the skill takes input.
• Pre-approved tools? Ask only if the skill chains specific tool calls in a way that would prompt the user repeatedly.

Resolve high-level shape first, fill in detail second. Do not pre-ask about every optional field; pull each in only when the conversation surfaces a reason.

2. Decide structure

Sketch the directory before writing files. If the body will reference references/foo.md or run scripts/bar.py, plan that now so the body and the bundled files stay consistent.

3. Write the frontmatter

Start with the minimal set and add fields only when the answers from step 1 forced a specific need:

---
description: <Third-person summary of what the skill does + when to use it.>
when_to_use: <Optional: separate slot for trigger phrases if description is busy.>
---

That is the whole frontmatter for most reference skills and many simple workflow skills. The directory name supplies name by default; do not set name unless you need a different display name from the directory.

Add other fields only when a specific condition holds (see the "Frontmatter is minimal by default" table earlier in this file for the condition per field):

• disable-model-invocation: true for irreversible side effects.
• argument-hint: and arguments: when the skill takes input.
• allowed-tools: when the body chains tool calls that would prompt the user.
• context: fork (+ agent:) when the body is a bounded actionable task.
• paths: when the skill is path-conditional.
• model: / effort: / hooks: only when the skill genuinely needs them.

description + when_to_use is the trigger surface, the only thing the model sees before deciding to load the skill. Claude Code truncates the combined entry at 1,536 characters in the skill listing (see Anthropic docs); anything past that is invisible to the trigger decision. Front-load the use case.

Triggering rules for the description text:

• Third person. "Summarizes a PR", not "I can summarize PRs" or "You can use this to summarize PRs". The description gets injected into the system prompt, mixed POV confuses skill discovery.
• Front-load the verb and the noun. Start with what the skill does, then the contexts that pull it in.