scaffold

What this skill does

# 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