Create Skill

---

name: create-skill description: Guide for creating a new Claude Code skill with the correct directory structure, front matter, and conventions. Use when creating or scaffolding a new skill. argument-hint: <skill-name> [--global]

Usage

Invoked as: /create-skill <skill-name> [--global]

The skill name is: $ARGUMENTS

Instructions

When creating a new skill, follow this structure precisely.

Step 1 — Determine scope

• Project skill (default): .claude/skills/<skill-name>/SKILL.md
• Global skill (if --global is passed): ~/.claude/skills/<skill-name>/SKILL.md

Global skills apply to all projects. Project skills apply only to the current repo.

Step 2 — Create the directory and file

<scope-path>/skills/<skill-name>/
└── SKILL.md        # Required

The directory name must be lowercase, using only letters, numbers, and hyphens. The directory name becomes the /slash-command name.

Only SKILL.md is required. Optional supporting files can be added alongside it:

<scope-path>/skills/<skill-name>/
├── SKILL.md           # Required — main instructions
├── template.md        # Optional — template for Claude to fill in
├── examples/          # Optional — example outputs
└── scripts/           # Optional — executable scripts

Step 3 — Write the SKILL.md with correct front matter

The file MUST start with YAML front matter between --- markers:

---
name: my-skill
description: What this skill does and when to use it.
---

Required and recommended fields

| Field | Required? | Description | |-------|-----------|-------------| | name | No (defaults to directory name) | Lowercase, numbers, hyphens only. Max 64 chars. | | description | Recommended | What the skill does and when to invoke it. Claude uses this to decide when to auto-load the skill. |

Optional fields

| Field | Description | |-------|-------------| | argument-hint | Hint shown during autocomplete, e.g. [file-path] or [issue-number] | | disable-model-invocation | Set to true to prevent Claude from auto-invoking (user only) | | user-invocable | Set to false to hide from / menu (Claude-only background knowledge) | | allowed-tools | Tools Claude can use without asking, e.g. Read, Grep, Bash(python *) | | model | Specific model to use when this skill is active | | context | Set to fork to run in an isolated subagent context | | agent | Subagent type when context: fork is set (e.g. Explore, Plan) |

Step 4 — Write the skill body

After the front matter, write the skill instructions in markdown. Follow these conventions:

1. Start with a ## Usage section showing invocation syntax and referencing $ARGUMENTS
2. Use numbered ### Step N — Title sections for multi-step workflows
3. Keep SKILL.md under 500 lines — move detailed reference material to supporting files
4. Reference supporting files so Claude knows when to load them:

   For API details, see [reference.md](reference.md)
   

Available substitution variables

| Variable | Description | |----------|-------------| | $ARGUMENTS | All arguments passed to the skill | | $ARGUMENTS[N] or $N | Specific argument by index (0-based) | | ${CLAUDE_SESSION_ID} | Current session ID |

Dynamic context injection

Use !command`` to run shell commands whose output is injected before Claude sees the skill:

Current branch: !`git branch --show-current`

Step 5 — Confirm the result

After creating the skill, report:

• The full path to the created SKILL.md
• The invocation command (e.g. /my-skill)
• Whether it is global or project-scoped

Quick reference — Minimal example

---
name: greet
description: Greet the user warmly. Use when the user says hello.
---

## Usage

Invoked as: `/greet $ARGUMENTS`

Say hello to the user by name if provided, otherwise just say hello.