Claude Code scaffold coach

Interactive wizard that identifies the right Claude Code component for your use case and generates a ready-to-use template.

Usage: /scaffold (no arguments needed). Start the conversation.

---

Phase 1: Discovery

Open with this prompt, then wait for the user's answer before asking anything else:

What do you want to automate or build? One sentence is enough to start.

Once you have a rough idea, ask the following questions in order. Skip a question if a previous answer already answers it.

Q1: Trigger

How is this triggered?

a) I run it myself with a command (e.g. /something) b) It should fire automatically when Claude takes an action (writes a file, runs bash, finishes a session...) c) It should apply all the time, every session, without me doing anything

• If b → likely a Hook (jump to Q_hook)
• If c → likely a Rule (jump to Q_rule)
• If a → continue with Q2

Q2: Domain expertise

Does this require deep, project-specific expertise? For example: knowing your GraphQL schema, your migration conventions, your internal API patterns, your cost model...

• If yes, deep expertise → likely an Agent (jump to Q_agent)
• If no, more of a checklist or procedure → continue with Q3

Q3: Complexity

How much context and logic does this involve?

a) A lot: multiple rules, domain-specific examples, nuanced judgment b) Straightforward: a few steps, a template, some bash

• If a → likely a Skill
• If b → likely a Command

Q4: Reuse scope

Who needs this?

a) Just me b) My whole team c) It needs to be invokable by other agents automatically

• c → strengthens Agent (needs a description: field that other agents can read)
• b → strengthens Command or Skill (shared config)
• a → can stay a simple personal Command

Q5: Output type

What should happen at the end?

a) A report or analysis: Claude reads and explains, no files touched b) Code or files generated c) An action taken (commit, push, API call...) d) Claude's behavior changes permanently (always does X, never does Y)

• a → read-only Agent (no Write or Bash in tools)
• b/c → Agent or Command/Skill with write access
• d → Rule, or Hook if conditional on a specific event

---

Internal decision tree (do not display, use to reason)

Triggered automatically?
  ├─ On Claude action (Write, Bash, SessionEnd...) -> Hook
  └─ Always active, no trigger -> Rule

Triggered manually?
  ├─ Deep domain expertise required?
  │   ├─ Yes + invokable by other agents -> Agent
  │   └─ Yes + manual use only -> Agent or Skill
  └─ Procedure / checklist, no special expertise?
      ├─ Complex, lots of project-specific context -> Skill
      └─ Simple, a few steps -> Command

Common hybrid cases:
  - Agent + Command: specialist agent + a shortcut command to invoke it
  - Rule + Hook: permanent behavior + blocking on a specific action
  - Skill + Agent: skill that delegates analysis to an agent

---

Phase 2: Recommendation

After the questions, display this structure:

## Diagnosis

You want to: [one-line summary of the use case]

## Recommendation: [TYPE]

**Why?**
[2-3 sentences: trigger type, complexity level, reuse scope]

**What it would NOT be, and why:**
- Not an agent because [short reason]
- Not a rule because [short reason]
[adjust based on actual candidates]

**Hybrid case?** [Yes / No]
[If yes: explain the combination and which file to create first]

---

Phase 3: Scaffold

Ask: "Generate the scaffold file?"

If yes, produce the template below based on the detected type.

---

Agent scaffold

---
name: [kebab-case-name]
description: "[What this agent does in one sentence. When to invoke it. Example triggers for other agents.]"
model: sonnet
tools: Read, Grep, Glob[, Write, Bash (add only if this agent must modify files or run commands)]
---

# [Agent Name]

[One paragraph: what this agent is for, what it is NOT for, and when to prefer another agent.]

## Context

[Stack, conventions, or domain knowledge this agent needs to be effective.]

## When to invoke

- [Concrete trigger 1]
- [Concrete trigger 2]
- [Concrete trigger 3]

## Protocol

### Step 1: Read context

```bash
# What to read before reasoning
cat CLAUDE.md 2>/dev/null

Step 2: Analyze

[What to look for. Patterns to detect. Red flags to surface.]

Step 3: Output

[Exact output format: use a markdown code block to show the structure.]

Red flags

Pattern	Risk
[pattern]	[impact]

What this agent does NOT do

• [Scope boundary 1]
• [Scope boundary 2: point to another agent if relevant]

**File**: `.claude/agents/[name].md`

---

### Command scaffold

```markdown
---
name: [name]
description: "[What this command does in one sentence]"
argument-hint: "[arg] [--flag]"
---

# [Command Name]

[Brief description. What problem it solves. When to use it vs alternatives.]

## Arguments

- `[arg]`: [description] (default: [value])
- `--flag`: [description]

## Usage

```bash
/[name]              # Basic usage
/[name] --flag       # With flag

---

Phase 1: [First phase name]

[What Claude does in this phase.]

# Example commands if applicable

Phase 2: [Second phase name]

[What Claude does.]

Phase 3: Output

[Output format. Use a markdown block to show the structure.]

$ARGUMENTS

**File**: `.claude/commands/[name].md`

---

### Skill scaffold

```markdown
---
name: [skill-name]
description: "[What this skill does. Trigger phrases that activate it. Usage: /[name] [arg]]"
---

# [Skill Name]

[What this skill does and when it applies. Distinguish from similar skills.]

## Trigger phrases

- "[phrase that activates this skill]"
- "[alternative phrasing]"

## When to use

- [Scenario 1]
- [Scenario 2]

## Workflow

### 1. [First action]: [brief description]

[Details]

### 2. [Second action]: [brief description]

[Details]

### 3. Deliver output

[Output format]

## Conventions to follow

[Project-specific rules, naming conventions, or patterns this skill must respect.]

## Common pitfalls

- [Mistake 1 and how to avoid it]
- [Mistake 2 and how to avoid it]

$ARGUMENTS

File: .claude/skills/[name].md

---

Hook scaffold

#!/usr/bin/env bash
# =============================================================================
# [name].sh: [PreToolUse | PostToolUse | UserPromptSubmit | Stop] Hook
# =============================================================================
# [What this hook does in one line]
# Fires on: [event] matching [tool or pattern]
#
# Exit 0 = allow / continue
# Exit 2 = block with message (PreToolUse only)
#
# stdin: JSON payload from Claude Code
# =============================================================================

set -euo pipefail

INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')

# --- Main logic ---

# [Your validation logic here]
# Example: block writes to protected paths
# FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
# if [[ "$FILE" == *"/secrets/"* ]]; then
#   echo "Blocked: writes to /secrets/ are not allowed" >&2
#   exit 2
# fi

exit 0

File: .claude/hooks/[name].sh

Also add to .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [{ "type": "command", "command": ".claude/hooks/[name].sh" }]
      }
    ]
  }
}

---

Rule scaffold

# [Rule Title] (Auto-loaded)

## Directive

[The rule in one imperative sentence.]

## When it applies

[Triggers, file types, or situations where this rule activates.]

## Required behavior

[What Claude must do concretely, be specific.]

## Anti-patterns

Do NOT:
- [Forbidden example]

Do:
- [Correct behavior]

---

**Auto-loaded**: This file is loaded automatically at session start.

File: .claude/rules/[name].md

Reference in CLAUDE.md if not in an auto-loaded directory.

---

Quick reference

If the user is unsure, show this table:

Type	Trigger	Expertise needed	Complexity	Typical example
Agent	Manual or automatic	High, domain-specific	Multi-step analysis	migration-reviewer, dbt-specialist
Command	Manual /name	Low to medium	Simple, a few steps	/commit, /pr, /release
Skill	Manual /name	Medium to high	Rich workflow, lots of context	tdd-workflow, api-review
Hook	Automatic on event	None (bash logic)	Script	security-gate.sh, format-on-save.sh
Rule	Permanent, every session	None (prose)	Instructions	no-direct-push.md, english-only.md

---

Sources

• Component types overview: Section 3
• Agent examples: agents/
• Hook examples: hooks/
• Skill examples: skills/