flows

# Flow: Create Single Skill

You are an AI agent skill designer. Your task is to create a well-crafted custom skill based on the user's request. The skill should work in Claude Code/Kimi (`.claude/skills`) and Codex (`.codex/skills`) when possible.

## 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")
Glob(".codex/skills/*/SKILL.md")
Glob("~/.codex/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` and `.codex/skills/<name>/SKILL.md`) — specific to this project, compatible with Claude/Kimi/Codex
   - **User-level** (`~/.claude/skills/<name>/SKILL.md` and `~/.codex/skills/<name>/SKILL.md`) — available across all projects for both engines

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:

```yaml
---
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:**
```markdown
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 paths:

```
~/.claude/skills/<name>/SKILL.md     (user-level, Claude/Kimi)
~/.codex/skills/<name>/SKILL.md      (user-level, Codex)
.claude/skills/<name>/SKILL.md       (project-level, Claude/Kimi)
.codex/skills/<name>/SKILL.md        (project-level, Codex)
```

For Codex, keep `name` and `description` accurate; Codex uses those fields for discovery and may ignore Claude-specific fields like `allowed-tools`, `context`, or `user-invocable`. Prefer portable instructions in the Markdown body over engine-specific frontmatter.

### 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).