Claude-Code-Workflow prompt-generator

• 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

@

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>

1. Determine Artifact Type

Parse

$ARGUMENTS

command

.claude/skills/

skill

agent

convert

Convert mode detection: If args contain a file path (

.md

$SOURCE_PATH

• .claude/commands/

  → command

• .claude/skills/*/SKILL.md

  → skill

• .claude/agents/

  → agent

Skill vs Command distinction: Skills (

.claude/skills/*/SKILL.md

@

Read()

@specs/command-design-spec.md

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

convert

Extract from

$ARGUMENTS

Common parameters (create mode):

$NAME

/^[a-z][a-z0-9-]*$/

deploy

gsd-planner

$DESCRIPTION

"Deploy to production with rollback"

Command-specific parameters:

$LOCATION

"project"

"user"

project

$GROUP

/^[a-z][a-z0-9-]*$/

issue

workflow

$ARGUMENT_HINT

"<phase> [--skip-verify]"

Agent-specific parameters:

$TOOLS

Read, Write, Bash, Glob

$SPAWNED_BY

/plan-phase orchestrator

Normalize: trim + lowercase for

$NAME

$LOCATION

$GROUP

3. Resolve Target Path

Command:

project

.claude/commands

user

~/.claude/commands

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

$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

$NAME

$DESCRIPTION

$ARGUMENT_HINT

$SPAWNED_BY

For commands — determine complexity:

For agents — determine expertise scope:

<role>

<role>

<role>

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

@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

Skills are command-like orchestrators but loaded progressively inline — they CANNOT use

@

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

@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

$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.

.claude/skills/*/SKILL.md

allowed-tools:

.claude/skills/

<process>

<step>

## N.

<role>

tools:

## Implementation

## Phase N

## Implementation

## Phase N

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

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:

$SRC_LINES

$OUT_LINES

$SRC_BLOCKS

$OUT_BLOCKS

$SRC_TABLES

$OUT_TABLES

$SRC_SECTIONS

$OUT_SECTIONS

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

Set

$TARGET_PATH = $SOURCE_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)

name

description

[...]

{...}

6b. Command-Specific Checks

<purpose>

<process>

## N.

<offer_next>

Agent({

subagent_type

<files_to_read>

<objective>

<output>

## TASK COMPLETE

## TASK BLOCKED

<offer_next>

<success_criteria>

6b-skill. Skill-Specific Checks

<purpose>

<required_reading>

<required_reading>

@

@specs/

@phases/

@./

<process>

## N.

Read("phases/...")

<success_criteria>

allowed-tools

6c. Agent-Specific Checks

tools

<role>

<role>

<role>

<files_to_read>

<role>

<rules>

<guidelines>

<output_contract>

<quality_gate>

AskUserQuestion

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

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

Write content to

$TARGET_PATH

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}"

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

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