| name | skill-creator |
| description | Guide for creating and editing Claude Code skills. Use when user wants to create a new skill, create a new slash command (skills are the unified primitive - commands live in skills/ now), update an existing skill, or needs help structuring a SKILL.md file. |
Skill Creator
Official docs: https://code.claude.com/docs/en/skills.md. Fetch when unsure about frontmatter semantics, subagent forking, hook integration, or recent features.
Process
1. Gather requirements
Ask the user:
- What task/domain does the skill cover?
- What specific use cases should it handle?
- Does it need executable scripts or just instructions?
- Any reference materials to include?
If the user's description is already clear, skip straight to drafting.
2. Determine placement
Infer from context, ask only if ambiguous:
- Global (
~/.claude/skills/) - across all projects
- Project (
<project>/.claude/skills/) - repo-specific
- Plugin (
<plugin>/plugins/<name>/skills/) - distributed via marketplace
3. Assess complexity
Simple (just write the SKILL.md):
- Purely instructional (workflow, guidelines, domain knowledge)
- No supporting files needed
Full (skill with bundled resources):
- Needs scripts for deterministic/repeated operations
- Needs reference docs (schemas, API docs, large knowledge bases)
- Needs assets (templates, images, fonts)
4. Draft the skill
Simple path: Create the directory and write SKILL.md directly.
Full path:
- Plan supporting files (what scripts/references/assets are needed)
- Create the skill directory and subdirs
- Write supporting files first (may need user input for assets/docs)
- Write SKILL.md last, referencing the supporting files
5. Review with user
Present draft and iterate. Skills improve most after real usage.
Skill Structure
skill-name/
├── SKILL.md # Main instructions (required)
├── references/ # Docs loaded into context on demand (optional)
│ ├── api-reference.md
│ └── schema.md
├── scripts/ # Deterministic code (optional)
│ └── helper.py
└── assets/ # Files used in output (optional)
└── template.html
Reference supporting files from SKILL.md so Claude knows they exist:
- For API details, see [references/api-reference.md](references/api-reference.md)
- For schema docs, see [references/schema.md](references/schema.md)
SKILL.md Format
---
name: skill-name
description: Brief description of capability. Use when [specific triggers].
---
# Skill Name
[Core instructions, workflows, and guidance]
Frontmatter reference
All fields are optional. Only description is recommended so Claude knows when to use the skill.
| Field | Required | Description |
|---|
name | No | Display name for the skill. If omitted, uses the directory name. Lowercase letters, numbers, and hyphens only (max 64 characters). |
description | Recommended | What the skill does and when to use it. Claude uses this to decide when to apply the skill. If omitted, uses the first paragraph of markdown content. Front-load the key use case: the combined description and when_to_use text is truncated at 1,536 characters in the skill listing to reduce context usage. |
when_to_use | No | Additional context for when Claude should invoke the skill, such as trigger phrases or example requests. Appended to description in the skill listing and counts toward the 1,536-character cap. |
argument-hint | No | Hint shown during autocomplete to indicate expected arguments. Example: [issue-number] or [filename] [format]. |
disable-model-invocation | No | Set to true to prevent Claude from automatically loading this skill. Use for workflows you want to trigger manually with /name. Default: false. |
user-invocable | No | Set to false to hide from the / menu. Use for background knowledge users shouldn't invoke directly. Default: true. |
allowed-tools | No | Tools Claude can use without asking permission when this skill is active. Accepts a space-separated string or a YAML list. |
model | No | Model to use when this skill is active. |
effort | No | Effort level when this skill is active. Overrides the session effort level. Default: inherits from session. Options: low, medium, high, xhigh, max; available levels depend on the model. |
context | No | Set to fork to run in a forked subagent context. |
agent | No | Which subagent type to use when context: fork is set. |
hooks | No | Hooks scoped to this skill's lifecycle. See Hooks in skills and agents for configuration format. |
paths | No | Glob patterns that limit when this skill is activated. Accepts a comma-separated string or a YAML list. When set, Claude loads the skill automatically only when working with files matching the patterns. Uses the same format as path-specific rules. |
shell | No | Shell to use for !`command` and ```! blocks in this skill. Accepts bash (default) or powershell. Setting powershell runs inline shell commands via PowerShell on Windows. Requires CLAUDE_CODE_USE_POWERSHELL_TOOL=1. |
Available string substitutions
Skills support string substitution for dynamic values in the skill content:
| Variable | Description |
|---|
$ARGUMENTS | All arguments passed when invoking the skill. If $ARGUMENTS is not present in the content, arguments are appended as ARGUMENTS: <value>. |
$ARGUMENTS[N] | Access a specific argument by 0-based index, such as $ARGUMENTS[0] for the first argument. |
$N | Shorthand for $ARGUMENTS[N], such as $0 for the first argument or $1 for the second. |
${CLAUDE_SESSION_ID} | The current session ID. Useful for logging, creating session-specific files, or correlating skill output with sessions. |
${CLAUDE_SKILL_DIR} | The directory containing the skill's SKILL.md file. For plugin skills, this is the skill's subdirectory within the plugin, not the plugin root. Use this in bash injection commands to reference scripts or files bundled with the skill, regardless of the current working directory. |
Additionally, !`<command>` (inline) and ```! fenced blocks preprocess shell command output into the prompt before Claude sees it.
Writing Guidelines
Description is the most important field. It's the only thing Claude sees when deciding which skill to load. Include:
- First sentence: what the skill does
- Second sentence: when to trigger it (keywords, file types, scenarios)
- Max 1024 chars, third person
Two types of skill content:
- Reference - knowledge Claude applies to current work (conventions, patterns, domain knowledge). Runs inline alongside conversation.
- Task - step-by-step instructions for a specific action (deploy, commit, code generation). Often paired with
disable-model-invocation: true.
Body should contain:
- Procedural knowledge non-obvious to Claude
- Concrete workflows with actionable steps
- References to supporting files so Claude knows they exist
Keep SKILL.md lean. Aim for under 200 lines, hard max 500. Move detailed material to supporting files.
When to Add Scripts
Add scripts/ when:
- Same code would be generated repeatedly
- Operation needs deterministic reliability
- Errors need explicit handling
Scripts save tokens and improve reliability vs regenerating code each time.
Path resolution: For plugin skills, reference scripts with ${CLAUDE_SKILL_DIR}/scripts/helper.js (relative paths won't resolve). Use ${CLAUDE_PLUGIN_ROOT} only when referencing files outside the skill's own directory. For global/project skills, relative paths work fine.
When to Split Files
Split content out of SKILL.md when:
- SKILL.md would exceed ~200 lines
- Content covers distinct domains (separate files per domain)
- Advanced features are rarely needed
- Large schemas, API docs, or knowledge bases
Prefer multiple focused files over one large reference file. E.g. api-reference.md, schema.md, examples.md rather than a single reference.md with everything.
For large files (>10k words), include grep patterns in SKILL.md so Claude can search efficiently.
Review Checklist
After drafting, verify:
