scaffold

# 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 ```markdown --- 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.] ```bash # 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 ```bash #!/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`: ```json { "hooks": { "PreToolUse": [ { "matcher": "Write", "hooks": [{ "type": "command", "command": ".claude/hooks/[name].sh" }] } ] } } ``` --- ### Rule scaffold ```markdown # [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](../../../guide/ultimate-guide.md) - Agent examples: [agents/](../../agents/) - Hook examples: [hooks/](../../hooks/) - Skill examples: [skills/](../../skills/)