Claude-Code-Workflow/.claude/skills/prompt-generator/SKILL.md

---
name: prompt-generator
description: Generate or convert Claude Code prompt files — command orchestrators, agent role definitions, or style conversion of existing files. Follows GSD-style content separation with built-in quality gates. Triggers on "create command", "new command", "create agent", "new agent", "convert command", "convert agent", "prompt generator".
allowed-tools: Read, Write, Edit, Bash, Glob, AskUserQuestion
---

<purpose>
Generate or convert Claude Code prompt files with concrete, domain-specific content. Three modes:

- **Create command** — new orchestration workflow at `.claude/commands/` or `~/.claude/commands/`
- **Create agent** — new role + expertise file at `.claude/agents/`
- **Convert** — restyle existing command/agent to GSD conventions with zero content loss

Content separation principle (from GSD): commands own orchestration flow; agents own domain knowledge.

Invoked when user requests "create command", "new command", "create agent", "new agent", "convert command", "convert agent", or "prompt generator".
</purpose>

<required_reading>
- @.claude/skills/prompt-generator/specs/command-design-spec.md
- @.claude/skills/prompt-generator/specs/agent-design-spec.md
- @.claude/skills/prompt-generator/specs/conversion-spec.md
- @.claude/skills/prompt-generator/templates/command-md.md
- @.claude/skills/prompt-generator/templates/agent-md.md
</required_reading>

<process>

## 1. Determine Artifact Type

Parse `$ARGUMENTS` to determine what to generate.

| Signal | Type |
|--------|------|
| "command", "workflow", "orchestrator" in args | `command` |
| "agent", "role", "worker" in args | `agent` |
| "convert", "restyle", "refactor" + file path in args | `convert` |
| Ambiguous or missing | Ask user |

**Convert mode detection:** If args contain a file path (`.md` extension) + conversion keywords, enter convert mode. Extract `$SOURCE_PATH` from args.

If ambiguous:

```
AskUserQuestion(
  header: "Artifact Type",
  question: "What type of prompt file do you want to generate?",
  options: [
    { label: "Command", description: "New orchestration workflow — process steps, user interaction, agent spawning" },
    { label: "Agent", description: "New role definition — identity, domain expertise, behavioral rules" },
    { label: "Convert", description: "Restyle existing command/agent to GSD conventions (zero content loss)" }
  ]
)
```

Store as `$ARTIFACT_TYPE` (`command` | `agent` | `convert`).

## 2. Validate Parameters

**If `$ARTIFACT_TYPE` is `convert`:** Skip to Step 2c.

Extract from `$ARGUMENTS` or ask interactively:

**Common parameters (create mode):**

| Parameter | Required | Validation | Example |
|-----------|----------|------------|---------|
| `$NAME` | Yes | `/^[a-z][a-z0-9-]*$/` | `deploy`, `gsd-planner` |
| `$DESCRIPTION` | Yes | min 10 chars | `"Deploy to production with rollback"` |

**Command-specific parameters:**

| Parameter | Required | Validation | Example |
|-----------|----------|------------|---------|
| `$LOCATION` | Yes | `"project"` or `"user"` | `project` |
| `$GROUP` | No | `/^[a-z][a-z0-9-]*$/` | `issue`, `workflow` |
| `$ARGUMENT_HINT` | No | any string | `"<phase> [--skip-verify]"` |

**Agent-specific parameters:**

| Parameter | Required | Validation | Example |
|-----------|----------|------------|---------|
| `$TOOLS` | No | comma-separated tool names | `Read, Write, Bash, Glob` |
| `$SPAWNED_BY` | No | which command spawns this agent | `/plan-phase orchestrator` |

Normalize: trim + lowercase for `$NAME`, `$LOCATION`, `$GROUP`.

## 3. Resolve Target Path

**Command:**

| Location | Base |
|----------|------|
| `project` | `.claude/commands` |
| `user` | `~/.claude/commands` |

```
If $GROUP:
  $TARGET_PATH = {base}/{$GROUP}/{$NAME}.md
Else:
  $TARGET_PATH = {base}/{$NAME}.md
```

**Agent:**

```
$TARGET_PATH = .claude/agents/{$NAME}.md
```

Check if `$TARGET_PATH` exists → `$FILE_EXISTS`.

## 4. Gather Requirements

**4a. Pattern discovery** — Find 3+ similar files in the project for style reference:

```bash
# For commands: scan existing commands
ls .claude/commands/**/*.md 2>/dev/null | head -5

# For agents: scan existing agents
ls .claude/agents/*.md 2>/dev/null | head -5
```

Read 1-2 similar files to extract patterns: section structure, naming conventions, XML tag usage, prompt style.

**4b. Domain inference** from `$NAME`, `$DESCRIPTION`, and context:

| Signal | Extract |
|--------|---------|
| `$NAME` | Action verb → step/section naming |
| `$DESCRIPTION` | Domain keywords → content structure |
| `$ARGUMENT_HINT` | Flags → parse_input logic (command only) |
| `$SPAWNED_BY` | Upstream contract → role boundary (agent only) |

**For commands — determine complexity:**

| Complexity | Criteria | Steps |
|------------|----------|-------|
| Simple | Single action, no flags | 3-5 numbered steps |
| Standard | 1-2 flags, clear workflow | 5-8 numbered steps |
| Complex | Multiple flags, agent spawning | 8-14 numbered steps |

**For agents — determine expertise scope:**

| Scope | Criteria | Sections |
|-------|----------|----------|
| Focused | Single responsibility | `<role>` + 1-2 domain sections |
| Standard | Multi-aspect domain | `<role>` + 2-4 domain sections |
| Expert | Deep domain with rules | `<role>` + 4-6 domain sections |

If unclear, ask user with AskUserQuestion.

## 5. Generate Content

Route to the appropriate generation logic based on `$ARTIFACT_TYPE`.

### 5a. Command Generation

Follow `@specs/command-design-spec.md` and `@templates/command-md.md`.

Generate a complete command file with:

1. **`<purpose>`** — 2-3 sentences: what + when + what it produces
2. **`<required_reading>`** — @ references to context files
3. **`<process>`** — numbered steps (GSD workflow style):
   - Step 1: Initialize / parse arguments
   - Steps 2-N: Domain-specific orchestration logic
   - Each step: banner display, validation, agent spawning via `Agent()`, error handling
   - Final step: status display + `<offer_next>` with next actions
4. **`<success_criteria>`** — checkbox list of verifiable conditions

**Command writing rules:**
- Steps are **numbered** (`## 1.`, `## 2.`) — follow `plan-phase.md` and `new-project.md` style
- Use banners for phase transitions: `━━━ SKILL ► ACTION ━━━`
- Agent spawning uses `Agent({ subagent_type, prompt, description, run_in_background })` pattern
- Prompt to agents uses `<objective>`, `<files_to_read>`, `<output>` blocks
- Include `<offer_next>` block with formatted completion status
- Handle agent return markers: `## TASK COMPLETE`, `## TASK BLOCKED`, `## CHECKPOINT REACHED`
- Shell blocks use heredoc for multi-line, quote all variables
- Include `<auto_mode>` section if command supports `--auto` flag

### 5b. Agent Generation

Follow `@specs/agent-design-spec.md` and `@templates/agent-md.md`.

Generate a complete agent definition with:

1. **YAML frontmatter** — name, description, tools, color (optional)
2. **`<role>`** — identity + spawned-by + core responsibilities + mandatory initial read
3. **Domain sections** (2-6 based on scope):
   - `<philosophy>` — guiding principles, anti-patterns
   - `<context_fidelity>` — how to honor upstream decisions
   - `<task_breakdown>` / `<output_format>` — concrete output rules with examples
   - `<quality_gate>` — self-check criteria before returning
   - Custom domain sections as needed
4. **Output contract** — structured return markers to orchestrator

**Agent writing rules:**
- `<role>` is ALWAYS first after frontmatter — defines identity
- Each section owns ONE concern — no cross-cutting
- Include concrete examples (good vs bad comparison tables) in every domain section
- Include decision/routing tables for conditional logic
- Quality gate uses checkbox format for self-verification
- Agent does NOT contain orchestration logic, user interaction, or argument parsing

### 5c. Convert Mode (Restyle Existing File)

**CRITICAL: Zero content loss.** Follow `@specs/conversion-spec.md`.

**Step 5c.1: Read and inventory source file.**

Read `$SOURCE_PATH` completely. Build content inventory:

```
$INVENTORY = {
  frontmatter: { fields extracted },
  sections: [ { name, tag, line_range, line_count, has_code_blocks, has_tables } ],
  code_blocks: count,
  tables: count,
  total_lines: count
}
```

**Step 5c.2: Classify source type.**

| Signal | Type |
|--------|------|
| Contains `<process>`, `<step>`, numbered `## N.` steps | command |
| Contains `<role>`, `tools:` in frontmatter, domain sections | agent |
| Flat markdown with `## Implementation`, `## Phase N` | command (unstructured) |
| Flat prose with role description, no process steps | agent (unstructured) |

**Step 5c.3: Build conversion map.**

Map every source section to its target location. Follow `@specs/conversion-spec.md` transformation rules.

**MANDATORY**: Every line of source content must appear in the conversion map. If a source section has no clear target, keep it as a custom section.

**Step 5c.4: Generate converted content.**

Apply structural transformations while preserving ALL content verbatim:
- Rewrap into GSD XML tags
- Restructure sections to match target template ordering
- Add missing required sections (empty `<quality_gate>`, `<output_contract>`) with `TODO` markers
- Preserve all code blocks, tables, examples, shell commands exactly as-is

**Step 5c.5: Content loss verification (MANDATORY).**

Compare source and output:

| Metric | Source | Output | Pass? |
|--------|--------|--------|-------|
| Total lines | `$SRC_LINES` | `$OUT_LINES` | output >= source × 0.95 |
| Code blocks | `$SRC_BLOCKS` | `$OUT_BLOCKS` | output >= source |
| Tables | `$SRC_TABLES` | `$OUT_TABLES` | output >= source |
| Sections | `$SRC_SECTIONS` | `$OUT_SECTIONS` | output >= source |

If ANY metric fails → STOP, display diff, ask user before proceeding.

Set `$TARGET_PATH = $SOURCE_PATH` (in-place conversion) unless user specifies output path.

### Content quality rules (both types):
- NO bracket placeholders (`[Describe...]`) — all content concrete
- NO generic instructions ("handle errors appropriately") — be specific
- Include domain-specific examples derived from `$DESCRIPTION`
- Every shell block: heredoc for multi-line, quoted variables, error exits

## 6. Quality Gate

**MANDATORY before writing.** Read back the generated content and validate against type-specific checks.

### 6a. Structural Validation (both types)

| Check | Pass Condition |
|-------|---------------|
| YAML frontmatter | Has `name` + `description` |
| No placeholders | Zero `[...]` or `{...}` bracket placeholders in prose |
| Concrete content | Every section has actionable content, not descriptions of what to write |
| Section count | Command: 3+ sections; Agent: 4+ sections |

### 6b. Command-Specific Checks

| Check | Pass Condition |
|-------|---------------|
| `<purpose>` | 2-3 sentences, no placeholders |
| `<process>` with numbered steps | At least 3 `## N.` headers |
| Step 1 is initialization | Parses args or loads context |
| Last step is status/report | Displays results or routes to `<offer_next>` |
| Agent spawning (if complex) | `Agent({` call with `subagent_type` |
| Agent prompt structure | `<files_to_read>` + `<objective>` or `<output>` blocks |
| Return handling | Routes on `## TASK COMPLETE` / `## TASK BLOCKED` markers |
| `<offer_next>` | Banner + summary + next command suggestion |
| `<success_criteria>` | 4+ checkbox items, all verifiable |
| Content separation | No domain expertise embedded — only orchestration |

### 6c. Agent-Specific Checks

| Check | Pass Condition |
|-------|---------------|
| YAML `tools` field | Lists tools agent needs |
| `<role>` is first section | Appears before any domain section |
| `<role>` has spawned-by | States which command spawns it |
| `<role>` has mandatory read | `<files_to_read>` instruction present |
| `<role>` has responsibilities | 3+ bullet points with verb phrases |
| Domain sections named | After domain concepts, not generic (`<rules>`, `<guidelines>`) |
| Examples present | Each domain section has 1+ comparison table or decision table |
| `<output_contract>` | Defines return markers (COMPLETE/BLOCKED/CHECKPOINT) |
| `<quality_gate>` | 3+ checkbox self-check items |
| Content separation | No `AskUserQuestion`, no banner display, no argument parsing |

### 6d. Quality Gate Result

Count errors and warnings:

| Gate | Condition | Action |
|------|-----------|--------|
| **PASS** | 0 errors, 0-2 warnings | Proceed to write |
| **REVIEW** | 1-2 errors or 3+ warnings | Fix errors, display warnings |
| **FAIL** | 3+ errors | Re-generate from step 5 |

If FAIL and second attempt also fails:

```
AskUserQuestion(
  header: "Quality Gate Failed",
  question: "Generated content failed quality checks twice. How to proceed?",
  options: [
    { label: "Show issues and proceed", description: "Write as-is, fix manually" },
    { label: "Provide more context", description: "I'll give additional details" },
    { label: "Abort", description: "Cancel generation" }
  ]
)
```

## 7. Write and Verify

**If `$FILE_EXISTS`:** Warn user before overwriting.

```bash
mkdir -p "$(dirname "$TARGET_PATH")"
```

Write content to `$TARGET_PATH` using Write tool.

**Post-write verification** — Read back and confirm file integrity:
- File exists and is non-empty
- Content matches what was generated (no corruption)
- File size is reasonable (command: 50-500 lines; agent: 80-600 lines)

**If verification fails:** Fix in-place with Edit tool.

## 8. Present Status

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 PROMPT-GEN ► {COMMAND|AGENT} GENERATED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Type: {command | agent}
File: {$TARGET_PATH}
Name: {$NAME}

| Section | Status |
|---------|--------|
| {section 1} | concrete |
| {section 2} | concrete |
| ... | ... |

Quality Gate: {PASS | REVIEW (N warnings)}

───────────────────────────────────────────────────────

## Next Up

1. Review: cat {$TARGET_PATH}
2. Test: /{invocation}

**If command + needs an agent:**
  /prompt-generator agent {agent-name} "{agent description}"

**If agent + needs a command:**
  /prompt-generator command {command-name} "{command description}"

───────────────────────────────────────────────────────
```

</process>

<success_criteria>
- [ ] Artifact type determined (command or agent)
- [ ] All required parameters validated
- [ ] Target path resolved correctly
- [ ] 1-2 similar existing files read for pattern reference
- [ ] Domain requirements gathered from description
- [ ] Content generated with concrete, domain-specific logic
- [ ] GSD content separation respected (commands = orchestration, agents = expertise)
- [ ] Quality gate passed (structural + type-specific checks)
- [ ] No bracket placeholders in final output
- [ ] File written and post-write verified
- [ ] Status banner displayed with quality gate result
</success_criteria>