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

name, description, allowed-tools

name	description	allowed-tools
command-generator	Command file generator - 5 phase workflow for creating Claude Code command files with YAML frontmatter. Generates .md command files for project or user scope. Triggers on "create command", "new command", "command generator".	Read, Write, Edit, Bash, Glob, AskUserQuestion

Generate Claude Code command .md files with concrete, domain-specific content in GSD style. Produces command files at project-level (`.claude/commands/`) or user-level (`~/.claude/commands/`) with YAML frontmatter, XML semantic tags (``, ``, ``, ``, ``), and actionable execution logic — NOT empty placeholders.

Invoked when user requests "create command", "new command", or "command generator".

<required_reading>

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

**Parse and validate all input parameters.**

Extract from $ARGUMENTS or skill args:

Parameter	Required	Validation	Example
$SKILL_NAME	Yes	/^[a-z][a-z0-9-]*$/, min 1 char	deploy, create
$DESCRIPTION	Yes	min 10 chars	"Deploy application to production"
$LOCATION	Yes	"project" or "user"	project
$GROUP	No	/^[a-z][a-z0-9-]*$/ or null	issue, workflow
$ARGUMENT_HINT	No	any string or empty	"<url> [--priority 1-5]"

Validation rules:

• Missing required param → Error with specific message (e.g., "skillName is required")
• Invalid $SKILL_NAME pattern → Error: "skillName must be lowercase alphanumeric with hyphens, starting with a letter"
• Invalid $LOCATION → Error: "location must be 'project' or 'user'"
• Invalid $GROUP pattern → Warning, continue

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

**Resolve target file path based on location and group.**

Path mapping:

Location	Base Directory
project	.claude/commands
user	~/.claude/commands (expand ~ to $HOME)

Path construction:

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

Check if $TARGET_PATH already exists → store as $FILE_EXISTS (true/false).

**Gather domain-specific requirements to generate concrete content.**

Infer the command's domain from $SKILL_NAME, $DESCRIPTION, and $ARGUMENT_HINT:

Signal	Extract
$SKILL_NAME	Action verb (deploy, create, analyze, sync) → step naming
$DESCRIPTION	Domain keywords → execution logic, error scenarios
$ARGUMENT_HINT	Flags/args → parse_input step details, validation rules
$GROUP	Command family → related commands, shared patterns

Determine command complexity:

Complexity	Criteria	Steps to Generate
Simple	Single action, no flags	2-3 steps
Standard	1-2 flags, clear workflow	3-4 steps
Complex	Multiple flags, multi-phase	4-6 steps

If complexity is unclear, ask user:

AskUserQuestion(
  header: "Command Scope",
  question: "What are the main execution steps for this command?",
  options: [
    { label: "Simple", description: "Single action: validate → execute → report" },
    { label: "Standard", description: "Multi-step: parse → process → verify → report" },
    { label: "Complex", description: "Full workflow: parse → explore → execute → verify → report" },
    { label: "I'll describe", description: "Let me specify the steps" }
  ]
)

Store as $COMMAND_STEPS, $ERROR_SCENARIOS, $SUCCESS_CONDITIONS.

**Generate concrete, domain-specific command content in GSD style.**

This is the core generation step. Draft the COMPLETE command file — not a template with placeholders — using the gathered requirements.

YAML Frontmatter:

---
name: $SKILL_NAME
description: $DESCRIPTION
argument-hint: $ARGUMENT_HINT  # only if provided
---

<purpose> section: Write 2-3 sentences describing:

• What the command does (action + target)
• When it's invoked (trigger conditions)
• What it produces (output artifacts or effects)

<required_reading> section: Infer from domain:

• If command reads config → @.claude/CLAUDE.md or relevant config files
• If command modifies code → relevant source directories
• If command is part of a group → other commands in the same group

<process> section with <step> blocks:

For each step in $COMMAND_STEPS, generate a <step name="snake_case"> block containing:

1. parse_input (always first, priority="first"):

   • Parse $ARGUMENTS for flags and positional args derived from $ARGUMENT_HINT
   • Include specific flag detection logic (e.g., if arguments contain "--env")
   • Include validation with specific error messages
   • Include decision routing table if multiple modes exist

2. Domain-specific execution steps (2-4 steps):

   • Each step has a bold action description
   • Include concrete shell commands, file operations, or tool calls
   • Use $UPPER_CASE variables for user input, ${computed} for derived values
   • Include conditional logic with specific conditions (not generic)
   • Reference actual file paths and tool names

3. report (always last):

   • Format output with banner and status
   • Include file paths, timestamps, next step suggestions

Shell Correctness Checklist (MANDATORY for every shell block):

Rule	Wrong	Correct
Multi-line output	echo "{ ... }" (unquoted multi-line)	cat <<'EOF' > file...EOF (heredoc)
Variable init	Use $VAR after conditional	VAR="default" BEFORE any conditional that sets it
Error exit	echo "Error: ..." (no exit)	echo "Error: ..." # (see code: E00X) + exit 1
Quoting	$VAR in commands	"$VAR" (double-quoted in all expansions)
Exit on fail	Command chain without checks	set -e or explicit `
Command from var	$CMD --flag (word-split fragile)	eval "$CMD" --flag or use array: cmd=(...); "${cmd[@]}"
Prerequisites	Implicit git/curl usage	Declare in <prerequisites> section

Golden Example — a correctly-written execution step:

<step name="run_deployment">
**Execute deployment to target environment.**

$DEPLOY_STATUS="pending"  # Initialize before conditional

```bash
# Save current state for rollback
cp .deploy/latest.json .deploy/previous.json 2>/dev/null || true

# Write deployment manifest via heredoc
cat <<EOF > .deploy/latest.json
{
  "env": "$ENV",
  "tag": "$DEPLOY_TAG",
  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "commit": "$(git rev-parse --short HEAD)",
  "status": "deploying"
}
EOF

# Execute deployment
if ! deploy_cmd --env "$ENV" --tag "$DEPLOY_TAG" 2>&1 | tee .deploy/latest.log; then
  echo "Error: Deployment to $ENV failed" # (see code: E004)
  exit 1
fi

$DEPLOY_STATUS="success"

Condition	Action
Deploy succeeds	Update status → "deployed", continue to verify
Deploy fails	Log error # (see code: E004), exit 1
$ROLLBACK_MODE	Load .deploy/previous.json, redeploy prior version

**Optional `<prerequisites>` section** (include when command uses external tools):

```markdown
<prerequisites>
- git (2.20+) — version control operations
- curl — health check endpoints
- jq — JSON processing (optional)
</prerequisites>

<error_codes> table: Generate 3-6 specific error codes:

• Derive from $ARGUMENT_HINT validation failures (E001-E003)
• Derive from domain-specific failure modes (E004+)
• Include 1-2 warnings (W001+)
• Each code has: Code, Severity, Description, Stage (which step triggers it)
• Cross-reference rule: Every # (see code: E00X) comment in <process> MUST have a matching row in <error_codes>, and every error code row MUST be referenced by at least one inline comment

<success_criteria> checkboxes: Generate 4-8 verifiable conditions:

• Input validation passed
• Each execution step completed its action
• Output artifacts exist / effects applied
• Report displayed

Quality rules for generated content:

• NO bracket placeholders ([Describe...], [List...]) — all content must be concrete
• Steps must contain actionable logic, not descriptions of what to do
• Error codes must reference specific failure conditions from this command's domain
• Success criteria must be verifiable (not "command works correctly")
• Every shell block must pass the Shell Correctness Checklist above
• Follow patterns from @.claude/skills/command-generator/templates/command-md.md for structural reference only

**Write generated content to target path.**

If $FILE_EXISTS: Warn: "Command file already exists at {path}. Will overwrite."

mkdir -p "$TARGET_DIR"

Write the drafted content to $TARGET_PATH using Write tool.

Verify: Read back the file and confirm:

• File exists and is non-empty
• Contains <purpose> tag with concrete content (no placeholders)
• Contains at least 2 <step name= blocks with shell code or tool calls
• Contains <error_codes> with at least 3 rows including Stage column
• Contains <success_criteria> with at least 4 checkboxes
• No unresolved {{...}} or [...] placeholders remain
• Every # (see code: E0XX) has a matching <error_codes> row (cross-ref check)
• Every shell block uses heredoc for multi-line output (no bare multi-line echo)
• All state variables initialized before conditional use
• All error paths include exit 1 after error message

If verification fails: Fix the content in-place using Edit tool.

Report completion:

Command generated successfully!

File: {$TARGET_PATH}
Name: {$SKILL_NAME}
Description: {$DESCRIPTION}
Location: {$LOCATION}
Group: {$GROUP or "(none)"}
Steps: {number of <step> blocks generated}
Error codes: {number of error codes}

Next Steps:
1. Review and customize {$TARGET_PATH}
2. Test: /{$GROUP}:{$SKILL_NAME} or /{$SKILL_NAME}

<error_codes>

Code	Severity	Description	Stage
E001	error	skillName is required	validate_params
E002	error	description is required (min 10 chars)	validate_params
E003	error	location is required ("project" or "user")	validate_params
E004	error	skillName must be lowercase alphanumeric with hyphens	validate_params
E005	error	Failed to infer command domain from description	gather_requirements
E006	error	Failed to write command file	write_file
E007	error	Generated content contains unresolved placeholders	write_file
W001	warning	group must be lowercase alphanumeric with hyphens	validate_params
W002	warning	Command file already exists, will overwrite	write_file
W003	warning	Could not infer required_reading, using defaults	draft_content

</error_codes>

<success_criteria>

• All required parameters validated ($SKILL_NAME, $DESCRIPTION, $LOCATION)
• Target path resolved with correct scope (project vs user) and group
• Command domain inferred from description and argument hint
• Concrete <purpose> drafted (no placeholders)
• 2-6 <step> blocks generated with domain-specific logic
• <error_codes> table generated with 3+ specific codes
• <success_criteria> generated with 4+ verifiable checkboxes
• File written to $TARGET_PATH and verified
• Zero bracket placeholders in final output
• Completion report displayed </success_criteria>