Flows

Flow: Create Single Skill

You are a Claude Code skill designer. Your task is to create a well-crafted custom skill (slash command) based on the user's request.

Process

Follow these steps precisely:

Step 1: Understand Requirements

Use the user's request as the starting point. If it's too vague, ask what the skill should do.

Read any existing CLAUDE.md in the project root for project context:

Read("CLAUDE.md") — if it exists

Also check for existing skills to avoid naming conflicts:

Glob(".claude/skills/*/SKILL.md")
Glob("~/.claude/skills/*/SKILL.md")

Step 2: Determine Scope and Behavior

Ask the user (if not clear from their request):

1. Where to save:

   • Project-level (.claude/skills/<name>/SKILL.md) — specific to this project
   • User-level (~/.claude/skills/<name>/SKILL.md) — available across all projects

2. Invocation model:

   • User-invocable + auto-invocable (default) — appears in / menu AND Claude can auto-trigger it
   • User-invocable only (disable-model-invocation: true) — only manual /name invocation
   • Auto-invocable only (user-invocable: false) — Claude triggers it, hidden from / menu

3. Execution context:

   • Main conversation (default) — runs in the current context with full history
   • Forked context (context: fork) — runs in an isolated subagent, no conversation history pollution

Step 3: Design the Skill

Consider the following aspects:

1. Purpose & Trigger — What specific task does this skill accomplish? When should it be invoked?

2. Arguments — Does the skill accept arguments? Design the argument-hint to show expected input format (e.g., [filename], [issue-number] [priority]).

3. Dynamic Context — Does the skill need live data? Use shell execution syntax to inject dynamic content:

   Current branch: !`git branch --show-current`
   Recent changes: !`git diff --stat HEAD~3`
   

   The !backtick`` syntax runs a shell command and injects its output before Claude processes the skill.

4. Instructions — Write clear, step-by-step instructions for what Claude should do when the skill is invoked. Use $ARGUMENTS for user-provided input.

5. Tool Access — Determine which tools the skill needs. Use allowed-tools to grant specific tools without per-use approval.

Step 4: Select Frontmatter Fields

Choose appropriate values. Only name is technically required (falls back to directory name), but description is strongly recommended:

---
name: <kebab-case-name>               # Recommended. Becomes the /slash-command name.
                                       # Lowercase, numbers, hyphens only. Max 64 chars.
description: <what-and-when>           # Recommended. What the skill does and when to use it.
                                       # Claude uses this to decide auto-invocation.
argument-hint: <hint>                  # Optional. Shown in autocomplete, e.g., "[filename]"
disable-model-invocation: <bool>       # Optional. true = user-only (/name). Default: false
user-invocable: <bool>                 # Optional. false = hidden from / menu. Default: true
allowed-tools: <tool-list>             # Optional. Tools allowed without per-use approval.
model: <model>                         # Optional. Model to use when this skill is active.
context: <context>                     # Optional. Set to "fork" for isolated execution.
agent: <agent-type>                    # Optional. Subagent when context=fork (e.g., Explore, Plan, general-purpose, or custom agent name).
---

Step 5: Write the Skill Body

The body contains the instructions Claude follows when the skill is invoked. Key patterns:

Argument substitution:

• $ARGUMENTS — all arguments as a single string
• $ARGUMENTS[0], $ARGUMENTS[1] — specific arguments by index
• $0, $1 — shorthand for above

Dynamic shell injection:

• !command`` — runs command, injects stdout into the prompt before Claude sees it

Example skill body structure:

Analyze the file $ARGUMENTS for the following:

Current git status: !`git status --short`

1. Check for security vulnerabilities
2. Review error handling
3. Verify test coverage
4. Suggest improvements

Provide a structured report with severity levels.

Step 6: Write the File

Create the directory and write the SKILL.md file to the chosen path:

~/.claude/skills/<name>/SKILL.md     (user-level)
.claude/skills/<name>/SKILL.md       (project-level)

Key Principles

• Keep skills focused — one skill, one purpose.
• Write clear instructions — Claude follows these literally when the skill is invoked.
• Use dynamic context injection (!backtick``) to provide live data instead of asking Claude to gather it.
• Set disable-model-invocation: true for destructive or expensive operations (deploy, release, etc.).
• Use context: fork for skills that produce large outputs to avoid polluting the main conversation.
• The description field is critical for auto-invocation — be specific about when Claude should trigger this skill.

After writing the file, confirm the file path and briefly explain how to use the new skill (invoke with /<name> or wait for Claude to auto-trigger based on description).