create-skill - SKILL.md Agent Skill

name: create-skill description: Use this skill when the user asks to "create a skill", "add a skill", "make a new skill", "build a skill", or wants to automate a repeated workflow into a reusable prompt. Guides creating a properly structured Claude Code skill.

Create Skill

Help the user create a new Claude Code skill in this project.

Step 1: Clarify the Skill's Purpose

Ask the user (or infer from context):

What task should the skill perform?
Is it reference content (conventions, patterns, domain knowledge that applies inline) or task content (step-by-step actions like deploy/commit/generate)?
Should Claude invoke it automatically, or only the user manually?
Are there specific trigger phrases or situations?

Step 2: Determine Placement

Project skills live at:

.claude/skills/<skill-name>/
├── SKILL.md          # Main instructions (required)
├── references/       # background knowledge, specs, checklists
├── examples/         # example inputs/outputs
└── scripts/          # helper shell scripts

Step 3: Write the SKILL.md

Use this frontmatter template:

---
name: skill-name
description: Use this skill when the user asks to "...", mentions "...", or wants to "...". Include specific trigger phrases.
---

Complete Frontmatter Reference

All fields are optional. Only description is recommended.

Field	Description
`name`	Display name / slash command. Lowercase letters, numbers, hyphens only (max 64 chars). Defaults to directory name.
`description`	What the skill does and when to use it. Claude uses this to decide when to auto-load. If omitted, uses first paragraph of content.
`argument-hint`	Hint shown during autocomplete (e.g., `[issue-number]` or `[filename] [format]`).
`disable-model-invocation`	`true` prevents Claude from auto-loading. Use for side-effect workflows (`/deploy`, `/send`). Description is removed from context.
`user-invocable`	`false` hides from `/` menu. Use for background knowledge. Description stays in context so Claude can auto-invoke.
`allowed-tools`	Tools Claude can use without asking permission when skill is active (e.g., `Read, Grep, Glob`).
`model`	Model to use when this skill is active.
`context`	Set to `fork` to run in a forked subagent context (isolated, no conversation history).
`agent`	Subagent type when `context: fork` is set. Options: `Explore`, `Plan`, `general-purpose`, or custom from `.claude/agents/`. Defaults to `general-purpose`.
`hooks`	Hooks scoped to this skill's lifecycle.

Invocation & Context Loading Matrix

Configuration	User can invoke?	Claude can invoke?	Context behavior
(default)	Yes	Yes	Description always in context; full skill loads when invoked
`disable-model-invocation: true`	Yes	No	Description not in context; full skill loads when user invokes
`user-invocable: false`	No	Yes	Description always in context; full skill loads when Claude invokes

Dynamic Context Injection

The !command`` syntax runs shell commands before the skill content is sent to Claude. The output replaces the placeholder — Claude only sees the result, not the command.

- Current branch: !`git branch --show-current`
- Staged files: !`git diff --name-only --cached`

Arguments & String Substitutions

Substitution	Description
`$ARGUMENTS`	All arguments passed when invoking. If not present in content, appended as `ARGUMENTS: <value>`.
`$ARGUMENTS[N]`	Access a specific argument by 0-based index (e.g., `$ARGUMENTS[0]`).
`$N`	Shorthand for `$ARGUMENTS[N]` (e.g., `$0`, `$1`, `$2`).
`${CLAUDE_SESSION_ID}`	Current session ID. Useful for logging or session-specific files.
`${CLAUDE_SKILL_DIR}`	Directory containing this SKILL.md. Use to reference bundled scripts/files regardless of cwd.

Example with positional arguments:

---
name: migrate-component
description: Migrate a component from one framework to another
argument-hint: [component] [from-framework] [to-framework]
---

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

Step 4: Write Effective Instructions

The body of SKILL.md is the prompt Claude follows. Best practices:

State the goal clearly at the top
Use numbered steps for sequential workflows
Reference supporting files with relative markdown links: [checklist.md](checklist.md)
Keep it focused — one skill per domain
Keep SKILL.md under 500 lines. Move detailed reference material to separate files.
Include "ultrathink" in skill content to enable extended thinking
For context: fork, the skill content becomes the subagent's prompt — must include an explicit task, not just guidelines

Add Supporting Files

Supporting files keep SKILL.md focused. Reference them so Claude knows when to load each:

## Additional resources

- For complete API details, see [reference.md](reference.md)
- For usage examples, see [examples.md](examples.md)

Step 5: Create the Files

Create .claude/skills/<skill-name>/SKILL.md with:

Frontmatter with name and description
Clear, step-by-step instructions
Any supporting files the skill references

Step 6: Register in Project Memory

If a CLAUDE.md file exists at the project root, append the new skill to reinforce discoverability. Add a bullet with the skill name and short description to the skills list:

- **skill-name**: Short description of what the skill does

If no CLAUDE.md exists, skip this step — skills are still auto-discovered from .claude/skills/.

Confirm the skill was created and explain how to test it: the user can invoke it with /<skill-name> or describe the situation that should auto-trigger it.

Troubleshooting

Skill not triggering: Check description includes keywords users would naturally say. Verify with "What skills are available?" or invoke directly with /skill-name.
Skill triggers too often: Make description more specific, or add disable-model-invocation: true.
Claude doesn't see all skills: Skill descriptions share a context budget (2% of context window, fallback 16K chars). Run /context to check for warnings. Override with SLASH_COMMAND_TOOL_CHAR_BUDGET env var.
Permission control: Use Skill(name) for exact match or Skill(name *) for prefix match in permission rules. Deny all with Skill in deny rules.