Prompt Generator

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

• Create command — new orchestration workflow at .claude/commands/ or ~/.claude/commands/
• Create skill — new skill file at .claude/skills/*/SKILL.md (progressive loading, no @ refs)
• Create agent — new role + expertise file at .claude/agents/
• Convert — restyle existing command/skill/agent to GSD conventions with zero content loss

Content separation principle (from GSD): commands/skills own orchestration flow; agents own domain knowledge. Skills are a variant of commands but loaded progressively inline — they CANNOT use @ file references.

Invoked when user requests "create command", "new command", "create skill", "new skill", "create agent", "new agent", "convert command", "convert skill", "convert agent", "prompt generator", or "优化". </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.

Convert mode detection: If args contain a file path (.md extension) + conversion keywords, enter convert mode. Extract $SOURCE_PATH from args. Auto-detect source type from path:

• .claude/commands/ → command
• .claude/skills/*/SKILL.md → skill
• .claude/agents/ → agent

Skill vs Command distinction: Skills (.claude/skills/*/SKILL.md) are loaded progressively inline into the conversation context. They CANNOT use @ file references — only Read() tool calls within process steps. See @specs/command-design-spec.md → "Skill Variant" section.

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: "Skill", description: "New skill file — progressive loading, no @ refs, inline Read() for external files" },
    { label: "Agent", description: "New role definition — identity, domain expertise, behavioral rules" },
    { label: "Convert", description: "Restyle existing command/agent/skill to GSD conventions (zero content loss)" }
  ]
)

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

2. Validate Parameters

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

Extract from $ARGUMENTS or ask interactively:

Common parameters (create mode):

Command-specific parameters:

Agent-specific parameters:

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

3. Resolve Target Path

Command:

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

Skill:

$TARGET_PATH = .claude/skills/{$NAME}/SKILL.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:

# 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:

For commands — determine complexity:

For agents — determine expertise scope:

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

5a-skill. Skill Generation (variant of command)

Follow @specs/command-design-spec.md → "Skill Variant" section.

Skills are command-like orchestrators but loaded progressively inline — they CANNOT use @ file references.

Generate a complete skill file with:

1. `<purpose>` — 2-3 sentences: what + when + what it produces 2. NO `<required_reading>` — skills cannot use @ refs. External files loaded via Read() within process steps. 3. `<process>` — numbered steps (GSD workflow style):

• Step 1: Initialize / parse arguments / set workflow preferences
• Steps 2-N: Domain-specific orchestration logic with inline Read("phases/...") for phase files
• Each step: validation, agent spawning via Agent(), error handling
• Final step: completion status or handoff to next skill via Skill()

4. `<success_criteria>` — checkbox list of verifiable conditions

Skill-specific writing rules:

• NO `<required_reading>` tag — @ syntax not supported in skills
• NO `@path` references anywhere in the file — use Read("path") within <process> steps
• Phase files loaded on-demand: Read("phases/01-xxx.md") within the step that needs it
• Frontmatter uses allowed-tools: (not argument-hint:)
• <offer_next> is optional — skills often chain via Skill() calls
• <auto_mode> can be inline within <process> step 1 or as standalone section

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.

Skill-specific conversion rules:

• NO `<required_reading>` — skills cannot use @ file references (progressive loading)
• NO `@path` references anywhere — replace with Read("path") within <process> steps
• If source has @specs/... or @phases/... refs, convert to Read("specs/...") / Read("phases/...")
• Follow @specs/conversion-spec.md → "Skill Conversion Rules" section

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:

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)

6b. Command-Specific Checks

6b-skill. Skill-Specific Checks

6c. Agent-Specific Checks

6d. Quality Gate Result

Count errors and warnings:

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.

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>

Agent Design Specification

Guidelines for Claude Code agent definition files (role + domain expertise). Agents own identity, knowledge, and quality standards — NOT orchestration flow.

Content Separation Principle

Agents are spawned by commands via Agent(). The agent file defines WHO the agent is and WHAT it knows. It does NOT define WHEN or HOW it gets invoked.

YAML Frontmatter

---
name: agent-name
description: One-line purpose. Spawned by /command-name orchestrator.
tools: Read, Write, Bash, Glob, Grep    # Tools this agent needs
color: green                             # Optional: terminal color
---

Naming convention: {domain}-{role} or {project}-{role} — e.g., gsd-planner, gsd-plan-checker, code-reviewer.

Content Structure

Agent files use XML semantic tags. <role> is ALWAYS first after frontmatter.

Section Catalog

Derived from GSD agent patterns (gsd-planner, gsd-plan-checker, gsd-phase-researcher):

Section Ordering Convention

<role>              ← Identity (always first)
<project_context>   ← How to orient in the project
<philosophy>        ← Guiding beliefs
<upstream_input>    ← What agent receives
<context_fidelity>  ← How to honor decisions
<core_principle>    ← Key insight
... domain sections ← Expertise (2-6 sections)
<output_contract>   ← Return protocol
<quality_gate>      ← Self-check (always last content section)

Section Writing Rules

<role> — Identity (ALWAYS FIRST)

Pattern from gsd-planner.md and gsd-plan-checker.md:

<role>
You are a {role name}. You {primary action verb} {what you produce}.

Spawned by:
- `/{command}` orchestrator (standard mode)
- `/{command} --flag` orchestrator (variant mode)
- `/{command}` in revision mode (updating based on checker feedback)

Your job: {One sentence — what downstream consumers get from you.}

**CRITICAL: Mandatory Initial Read**
If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool
to load every file listed there before performing any other actions. This is your
primary context.

**Core responsibilities:**
- **FIRST: {Most important action}** ({why it's first})
- {Responsibility 2 — verb phrase}
- {Responsibility 3 — verb phrase}
- {Responsibility 4 — verb phrase}
- Return structured results to orchestrator
</role>

<project_context> — Project Discovery

Pattern from gsd-planner.md:

<project_context>
Before {acting}, discover project context:

**Project instructions:** Read `./CLAUDE.md` if it exists. Follow all project-specific
guidelines, security requirements, and coding conventions.

**Project skills:** Check `.claude/skills/` directory if exists:
1. List available skills (subdirectories)
2. Read `SKILL.md` for each skill
3. Load specific files as needed during {action}
4. Ensure {output} accounts for project patterns
</project_context>

<philosophy> — Guiding Principles

Pattern from gsd-planner.md:

<philosophy>
## {Principle Name}

{Core belief about how this agent approaches work.}

| Context Usage | Quality | Agent's State |
|---------------|---------|---------------|
| 0-30% | PEAK | Thorough |
| 50-70% | DEGRADING | Efficiency mode |
| 70%+ | POOR | Rushed |

**Anti-patterns (delete if seen):**
- {Anti-pattern 1 with specific indicator}
- {Anti-pattern 2 with specific indicator}
</philosophy>

<upstream_input> — Structured Input Handling

Pattern from gsd-plan-checker.md:

<upstream_input>
**{Input name}** (if exists) — {Source description}

| Section | How You Use It |
|---------|----------------|
| `## Section A` | LOCKED — {must implement exactly}. Flag if contradicted. |
| `## Section B` | Freedom areas — {can choose approach}, don't flag. |
| `## Section C` | Out of scope — {must NOT include}. Flag if present. |
</upstream_input>

<context_fidelity> — Decision Honoring

Pattern from gsd-planner.md:

<context_fidelity>
## CRITICAL: User Decision Fidelity

**Before creating ANY {output}, verify:**

1. **Locked Decisions** — MUST be implemented exactly as specified
   - If user said "use library X" → {output} MUST use X, not alternative
   - If user said "card layout" → {output} MUST implement cards

2. **Deferred Ideas** — MUST NOT appear in {output}
   - If user deferred "search" → NO search tasks allowed

3. **Discretion Areas** — Use your judgment
   - Make reasonable choices and document in {output}

**Self-check before returning:**
- [ ] Every locked decision has coverage
- [ ] No deferred idea appears
- [ ] Discretion areas handled reasonably

**If conflict exists** (research vs user decision):
- Honor the user's locked decision
- Note: "Using X per user decision (research suggested Y)"
</context_fidelity>

Domain Sections — One Concern Each

Name sections after the domain concept. Include concrete examples in EVERY section.

Required elements per domain section:

Example from gsd-planner.md `<task_breakdown>`:

<task_breakdown>
## Task Anatomy

Every task has four required fields:

**<files>:** Exact paths.
- Good: `src/app/api/auth/login/route.ts`
- Bad: "the auth files"

**<action>:** Specific instructions.
- Good: "Create POST endpoint accepting {email, password}, validates using bcrypt,
  returns JWT in httpOnly cookie with 15-min expiry. Use jose library."
- Bad: "Add authentication"

## Specificity Examples

| TOO VAGUE | JUST RIGHT |
|-----------|------------|
| "Add auth" | "Add JWT auth with refresh rotation, jose library, httpOnly cookie" |
| "Style the dashboard" | "Tailwind: 3-col grid on lg, 1 on mobile, card shadows, hover states" |

**Test:** Could a different agent execute without clarifying questions?
</task_breakdown>

<output_contract> — Return Protocol

<output_contract>
## Return Protocol

Return ONE of these markers as the LAST section of output:

### Success

TASK COMPLETE

{Summary of what was produced} {Artifact locations: file paths} {Key metrics: counts, coverage}

### Blocked

TASK BLOCKED

Blocker: {What's missing or preventing progress} Need: {Specific action/info that would unblock} Attempted: {What was tried before declaring blocked}

### Checkpoint (needs user decision)

CHECKPOINT REACHED

Question: {Decision needed from user} Context: {Why this matters} Options: 1. {Option A} — {effect on output} 2. {Option B} — {effect on output}

</output_contract>

<quality_gate> — Self-Check (ALWAYS LAST)

<quality_gate>
Before returning, verify:
- [ ] {Check 1 — concrete, grep-verifiable}
- [ ] {Check 2 — concrete, counts/exists}
- [ ] {Check 3 — concrete, structural}
- [ ] {Check 4 — no prohibited content}
</quality_gate>

Anti-Patterns

Command Design Specification

Guidelines for Claude Code command files (orchestration workflows). Commands own process flow, user interaction, and agent coordination — NOT domain expertise.

Content Separation Principle

YAML Frontmatter

---
name: command-name           # Required: lowercase with hyphens
description: Description     # Required: brief purpose
argument-hint: "[args]"      # Optional: argument format hint
allowed-tools: Tool1, Tool2  # Optional: restricted tool set
---

Path Structure

.claude/commands/deploy.md           # Top-level command
.claude/commands/issue/create.md     # Grouped command
~/.claude/commands/global-status.md  # User-level command
.claude/skills/my-skill/SKILL.md     # Skill file (see Skill Variant below)

Content Structure

Commands use XML semantic tags with process steps inside <process>:

Skill Variant

Skills (.claude/skills/*/SKILL.md) follow command structure with critical differences due to progressive loading — skills are loaded inline into the conversation context, NOT via file resolution.

Key Differences: Skill vs Command

Skill-Specific Rules

1. NO `<required_reading>` tag — Skills cannot use @ file references. All external context must be loaded via Read() tool calls within <process> steps.

2. Progressive phase loading — For multi-phase skills with phase files in phases/ subdirectory, use inline Read():

   // Within process step: Load phase doc on-demand
   Read("phases/01-session-discovery.md")
   // Execute phase logic...

3. Self-contained content — All instructions, rules, and logic must be directly in the SKILL.md or loaded via Read() at runtime. No implicit file dependencies.

4. Frontmatter uses `allowed-tools:` instead of argument-hint::

   ---
   name: my-skill
   description: What this skill does
   allowed-tools: Agent, Read, Write, Bash, Glob, Grep
   ---

Skill Content Structure

Note: <offer_next> is less common in skills since skills often chain to other skills via Skill() calls.

Step Styles

GSD uses two step styles. Choose based on command nature:

Style A: Numbered Steps (for complex orchestrators)

Used by: plan-phase.md, new-project.md, research-phase.md

Best for: Multi-agent orchestration, long workflows with branching, revision loops.

<process>

## 1. Initialize

Load context, parse arguments.

## 2. Validate Phase

Check preconditions.

## 3. Spawn Agent

Display banner, construct prompt, spawn.

## 4. Handle Result

Route on return markers.

## 5. Present Status

Display offer_next.

</process>

Style B: Named <step> Blocks (for focused commands)

Used by: execute-phase.md, discuss-phase.md, verify-work.md

Best for: Sequential steps, clear atomic actions, step-level priority.

<process>

<step name="initialize" priority="first">
Load context, parse arguments.
</step>

<step name="validate_phase">
Check preconditions.
</step>

<step name="spawn_agent">
Construct prompt, spawn agent.
</step>

<step name="report">
Display results.
</step>

</process>

Which style to use?

Init Pattern

Most GSD commands start by loading context via CLI tools:

INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init {command} "${ARG}")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi

For non-GSD commands, the equivalent is reading config/state files:

# Read project state
CONFIG=$(cat .claude/config.json 2>/dev/null || echo '{}')

Banner Style

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 SKILL ► ACTION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Display banners before major phase transitions (agent spawning, user decisions, completion).

Agent Spawning Pattern

Commands spawn agents via Agent() with structured prompts:

Agent({
  subagent_type: "agent-name",
  prompt: filled_prompt,
  description: "Verb Phase {X}",
  run_in_background: false
})

Prompt Structure for Agents

The prompt passed to agents uses XML blocks:

<objective>
What to accomplish — specific and measurable.
</objective>

<files_to_read>
- {path1} (description — what this file provides)
- {path2} (description)
</files_to_read>

<additional_context>
**Phase:** {number}
**Mode:** {standard | revision | gap_closure}
Extra info the agent needs.
</additional_context>

<output>
Write to: {output_path}
</output>

Return Handling

Commands route on agent return markers:

## Handle Agent Return

- **`## TASK COMPLETE`:** Display confirmation, continue to next step.
- **`## TASK BLOCKED`:** Display blocker, offer user options:
  1) Provide context  2) Skip  3) Abort
- **`## CHECKPOINT REACHED`:** Present question to user, relay response.

Revision Loop Pattern

For commands that iterate between generation and verification:

## N. Revision Loop (Max 3 Iterations)

Track `iteration_count` (starts at 1).

**If iteration_count < 3:**
- Display: "Sending back for revision... (iteration {N}/3)"
- Spawn agent with revision prompt + checker issues
- After agent returns → spawn checker again, increment count

**If iteration_count >= 3:**
- Display remaining issues
- Offer: 1) Force proceed  2) Provide guidance  3) Abandon

Auto Mode Pattern

Commands supporting --auto flag define behavior in <auto_mode>:

<auto_mode>
## Auto Mode Detection

Check if `--auto` flag is present in $ARGUMENTS.

**If auto mode:**
- Skip confirmation prompts
- Use smart defaults for optional choices
- Auto-approve intermediate results
- Chain to next command on success

**Document requirement (if applicable):**
- What --auto requires as input
- Error message if requirements not met
</auto_mode>

offer_next Pattern

<offer_next>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 SKILL ► TASK COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

**{Summary line}**

| Key | Value |
|-----|-------|
| ... | ...   |

Status: {metric 1} | {metric 2}

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

## Next Up

**{Primary next action}**

/{next-command} {args}

<sub>/clear first — fresh context window</sub>

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

**Also available:**
- /{alt-1} — description
- /{alt-2} — description

───────────────────────────────────────────────────────
</offer_next>

AskUserQuestion Pattern

For user decisions within commands:

AskUserQuestion(
  header: "Context",
  question: "Descriptive question?",
  options: [
    { label: "Option A", description: "Effect of choosing A" },
    { label: "Option B", description: "Effect of choosing B" }
  ]
)

If "Option A": {action}
If "Option B": {action}

Shell Correctness Rules

Step Naming Conventions

Conversion Specification

Rules for restyling existing command/agent files to GSD conventions. Zero content loss is mandatory.

Core Principle

Conversion = structural transformation, NOT content rewriting. Every line of source content must appear in the output. Only the container (XML tags, section ordering, frontmatter format) changes.

Content Loss Prevention Protocol

Pre-conversion Inventory

Before converting, count:

• $SRC_LINES — total non-empty lines
• $SRC_BLOCKS — code block count (``` pairs)
• $SRC_TABLES — table count (lines starting with |)
• $SRC_SECTIONS — section count (## headers)

Post-conversion Verification

Diff Display

After conversion, show summary:

Conversion Summary:
  Source: {path} ({src_lines} lines, {src_blocks} code blocks)
  Output: {path} ({out_lines} lines, {out_blocks} code blocks)
  Delta:  {+/-} lines, {+/-} code blocks
  New sections added: {list of TODO sections}

Artifact Type Detection

Before applying conversion rules, determine the source type:

Skill detection signals: allowed-tools: in frontmatter, located in .claude/skills/ directory, progressive phase loading pattern (Read("phases/..."))

Skill Conversion Rules

Critical: No @ References

Skills are loaded progressively inline into the conversation context. They CANNOT use @ file references — these only work in commands.

Source Pattern → Target Pattern (Skill)

What NOT to Add (Skill-Specific)

What to ADD (Skill-Specific)

Frontmatter Conversion (Skill)

Command Conversion Rules

Source Pattern → Target Pattern

Frontmatter Conversion

Section Wrapping

Content that was under plain ## headers gets wrapped in XML tags:

## Overview / ## Core Principle  → content moves to <purpose>
## Process / ## Implementation  → content moves to <process>
## Success Criteria             → content moves to <success_criteria>
## Error Codes                  → preserve as-is (optional section)

Everything else: Wrap in appropriate GSD tag or keep as custom section inside <process>.

What to ADD (with TODO markers)

Agent Conversion Rules

Source Pattern → Target Pattern

Frontmatter Conversion

Section Restructuring

1. `<role>` MUST be first — gather identity content from wherever it appears 2. Add "Spawned by:" if missing — infer from description or mark <!-- TODO: specify spawner --> 3. Add "Mandatory Initial Read" block if missing 4. Rename generic sections: <rules> → descriptive name based on content 5. Add `<output_contract>` if missing — with TODO marker 6. Add `<quality_gate>` if missing — with TODO marker

What NOT to Change

• Code blocks inside sections — preserve exactly
• Tables — preserve exactly
• Concrete examples (good/bad comparisons) — preserve exactly
• Shell commands — preserve exactly
• Agent prompts — preserve exactly
• Domain-specific terminology — preserve exactly

Batch Conversion

For converting multiple files:

# List candidates
ls .claude/commands/**/*.md .claude/agents/*.md

# Convert one at a time, verify each
/prompt-generator convert .claude/commands/issue/new.md
/prompt-generator convert .claude/agents/universal-executor.md

Anti-Patterns

Agent Template — Structural Reference

Defines the structural pattern for generated agent definition files. The generator uses this as a guide to produce concrete, domain-specific content — NOT as a literal copy target.

Required Structure

---
name: {$NAME}
description: {One-line purpose. Spawned by /command-name orchestrator.}
tools: {Read, Write, Bash, Glob, Grep}
color: {green|blue|yellow|red}  # optional
---

<role>
You are a {role name}. You {primary action} {what you produce}.

Spawned by:
- `/{command}` orchestrator (standard mode)
- `/{command} --flag` orchestrator (variant mode)

Your job: {One sentence — what downstream consumers get from you.}

**CRITICAL: Mandatory Initial Read**
If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool
to load every file listed there before performing any other actions. This is your
primary context.

**Core responsibilities:**
- {Verb phrase — primary task}
- {Verb phrase — secondary task}
- {Verb phrase — quality assurance}
- Return structured results to orchestrator
</role>

<philosophy>
## {Guiding Principle Name}

{Core beliefs — 3-5 bullet points}

**Anti-patterns (delete if seen):**
- {Anti-pattern 1}
- {Anti-pattern 2}
</philosophy>

<{domain_section_1}>
## {Domain Concept Name}

{Rules, heuristics, decision tables for this aspect.}

| {Condition} | {Action} |
|-------------|----------|
| ...         | ...      |

{Concrete examples — good vs bad:}

| TOO VAGUE | JUST RIGHT |
|-----------|------------|
| "..." | "..." |
</{domain_section_1}>

<{domain_section_2}>
## {Another Domain Concept}

{Format templates, structural rules, required fields.}

Every {output unit} has {N} required fields:
- **<field_1>:** {What it contains, why it matters}
- **<field_2>:** {What it contains, why it matters}
</{domain_section_2}>

<output_contract>
## Return Protocol

Agent returns one of these markers to the orchestrator:

### Success

TASK COMPLETE

{Structured output summary} {Artifact locations}

### Blocked

TASK BLOCKED

Blocker: {What's missing} Need: {What would unblock}

### Checkpoint

CHECKPOINT REACHED

Question: {Decision needed from user} Options: 1. {Option A} — {effect} 2. {Option B} — {effect}

</output_contract>

<quality_gate>
Before returning, verify:
- [ ] {Check 1 — concrete, verifiable}
- [ ] {Check 2 — concrete, verifiable}
- [ ] {Check 3 — concrete, verifiable}
- [ ] {Check 4 — concrete, verifiable}
</quality_gate>

Section Design Guidelines

Section Naming

Name sections after the domain concept they cover:

Section Independence

Each section owns ONE concern. Test: can you explain the section's scope in one sentence?

Example Density

Domain sections MUST include concrete examples. Minimum per section:

Command Template — Structural Reference

Defines the structural pattern for generated command files. The generator uses this as a guide to produce concrete, domain-specific content — NOT as a literal copy target.

Required Structure

---
name: {$NAME}
description: {$DESCRIPTION}
argument-hint: {$ARGUMENT_HINT}  # omit if empty
allowed-tools: {tools}           # omit if unrestricted
---

<purpose>
{2-3 sentences: what it does + when invoked + what it produces}
</purpose>

<required_reading>
{@ references to files needed before execution}
</required_reading>

<process>

## 1. Initialize

{Load context, parse $ARGUMENTS, validate preconditions.}

{Argument table:}
| Flag/Arg | Required | Description |
|----------|----------|-------------|
| `$ARG1`  | Yes      | ...         |
| `--flag` | No       | ...         |

{Validation: missing required → error, invalid → error with usage hint.}

## 2. {Domain Action}

{Display banner:}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ SKILL ► ACTION ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

{Core orchestration logic — file checks, state validation, conditional routing.}

## 3. Spawn Agent (if applicable)

{Construct prompt with <files_to_read>, <objective>, <output> blocks.}

Agent({ subagent_type: "{agent-name}", prompt: filled_prompt, description: "{Verb} {target}", run_in_background: false })

## 4. Handle Result

{Route on agent return markers:}
- `## TASK COMPLETE` → continue to next step
- `## TASK BLOCKED` → display blocker, offer options
- `## CHECKPOINT REACHED` → present to user, relay response

## N. Present Status

{Route to <offer_next>.}

</process>

<offer_next>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 SKILL ► TASK COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

**{Summary line}**

{Status table or key-value pairs}

## Next Up

/{next-command} {args}

**Also available:**
- /{alt-command-1} — description
- /{alt-command-2} — description
</offer_next>

<success_criteria>
- [ ] {Precondition validated}
- [ ] {Core action completed}
- [ ] {Agent spawned and returned (if applicable)}
- [ ] {Output artifact produced / effect applied}
- [ ] {Status displayed to user}
</success_criteria>

Step Naming Conventions

Content Quality Rules