---
name: create-skill
description: Create or improve a Claude Code skill — gathers requirements, selects agent type and frontmatter, generates a SKILL.md following best practices. Use when the user wants to create a skill, turn a workflow into a skill, improve an existing skill, or automate a repeating task as a slash command.
disable-model-invocation: true
argument-hint: "[skill-name or 'improve existing-skill-name']"
---

# Create or Improve Skill

Target: `$ARGUMENTS`

## Context

Existing project skills:
!`ls .claude/skills/ 2>/dev/null`

## Detect Mode

- If `$ARGUMENTS` names an existing skill (check dirs above) → **Improve mode**
- Otherwise → **Create mode**

---

## Create Mode

### 1. Capture intent

Check if the current conversation already contains a workflow the user wants to turn into a skill. If so, extract: tools used, sequence of steps, corrections made, input/output formats. Confirm with the user before proceeding.

If no prior context, gather requirements:
- What does this skill do? (one sentence)
- When should someone use it? (trigger phrases, contexts)
- What arguments does it expect? (file path, name, or none)
- Does it produce new files, modify existing files, or output analysis?
- Does it need live data at invocation time? (git diff, shell output)
- Scope: personal skill (all projects) or project-only?

### 2. Research

Read 2-3 existing skills closest in nature to the user's intent. Use them as examples of project conventions.

Read `${CLAUDE_SKILL_DIR}/references/frontmatter-spec.md` for the complete frontmatter specification.
Read `${CLAUDE_SKILL_DIR}/references/writing-guide.md` for skill writing best practices.

### 3. Determine frontmatter

Select the appropriate `agent` based on domain:

| Agent | Domain |
|---|---|
| `frontend-architect` | UI, components, accessibility |
| `backend-architect` | APIs, databases, server logic |
| `code-reviewer` | Code review, quality analysis |
| `test-engineer` | Tests, test strategy |
| `security-auditor` | Security, threat modeling |
| `prompt-engineer` | Prompts, LLM config |
| `documentation-expert` | Docs, ADRs |
| _(omit + no fork)_ | Multi-file coordination, interactive workflows |

Decide: `context: fork` for standalone deliverables (new file, analysis report). Omit for interactive workflows or multi-file coordination.

Always include `disable-model-invocation: true` (project convention).

### 4. Write the SKILL.md

Structure:
- H1 title — short action phrase
- One-liner referencing `$ARGUMENTS`
- Context section (optional) — `!` backtick for live data
- Steps — numbered, imperative:
  - Step 1: read project context
  - Middle: core logic
  - Last: output or summary
- Output format (if structured) — markdown template in fenced block

### 5. Write file

Based on scope choice:
- Personal: `~/.claude/skills/$NAME/SKILL.md`
- Project: `.claude/skills/$NAME/SKILL.md`

### 6. Verify and suggest tests

Read back the file and check:
- [ ] Valid YAML frontmatter
- [ ] Lowercase-hyphen name, no collision with existing skills
- [ ] Description with trigger contexts (slightly "pushy")
- [ ] Body: H1, steps, $ARGUMENTS reference
- [ ] Length appropriate (30-70 focused, up to 500 complex)

Propose 2-3 realistic test prompts including one edge case.

---

## Improve Mode

### 1. Read the existing skill

Read the full SKILL.md and any bundled resources in its directory.

### 2. Diagnose issues

Read `${CLAUDE_SKILL_DIR}/references/writing-guide.md` for evaluation criteria.

Analyze against:
- Description quality — is it "pushy" enough? Does it cover trigger contexts?
- Instruction clarity — does it explain WHY, not just rules?
- Structure — follows project conventions?
- Length — is it concise or bloated?
- Filler — does every sentence change agent behavior?

### 3. Propose improvements

Show a before/after diff of proposed changes with rationale for each change.
Apply only after user approval.

### 4. Suggest test prompts

Propose 2-3 prompts to verify the improved skill works as expected.