<required_reading> @~/.maestro/workflows/run-mode.md </required_reading>

Skill Generator

Meta-skill for creating new Claude Code skills with configurable execution modes.

Run Lifecycle

Follow ~/.maestro/workflows/run-mode.md. If an orchestrator injected a birth packet, use its exact locator, resolved task, and structured continuation directly. Otherwise negotiate capabilities and follow the receipt-chained self-start recipe: session open, fenced session chain insert --command skill-generator --arg "<task text>", then fenced run next, using one actor identity, distinct request IDs, and the exact revision returned by each receipt. Never send raw task prose through --input; it accepts only sealed same-Session Artifact IDs. Retain the exact locator, revisions, run_id, and run_dir; all {run_dir}/... paths below refer to it. Close per Phase 5.

Pre-load (before execution)

1. Codebase docs: If .workflow/codebase/ARCHITECTURE.md exists, read for project context
2. Specs: maestro load --type spec --category coding — load coding conventions
3. Wiki knowledge: maestro search "skill design optimization" --json — top 5 entries as prior context
4. All optional — proceed without if unavailable

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                    Skill Generator                               │
│                                                                  │
│  Input: User Request (skill name, purpose, mode)                │
│                         ↓                                        │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  Phase 0-5: Sequential Pipeline                          │    │
│  │  ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐             │    │
│  │  │ P0 │→│ P1 │→│ P2 │→│ P3 │→│ P4 │→│ P5 │             │    │
│  │  │Spec│ │Req │ │Dir │ │Gen │ │Spec│ │Val │             │    │
│  │  └────┘ └────┘ └────┘ └─┬──┘ └────┘ └────┘             │    │
│  │                         │                                │    │
│  │                    ┌────┴────┐                           │    │
│  │                    ↓         ↓                           │    │
│  │              Sequential  Autonomous                      │    │
│  │              (phases/)   (actions/)                      │    │
│  └─────────────────────────────────────────────────────────┘    │
│                         ↓                                        │
│  Output: .claude/skills/{skill-name}/ (complete package)        │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Execution Modes

Mode 1: Sequential (Fixed Order)

Traditional linear execution model, phases execute in numeric prefix order.

Phase 01 -> Phase 02 -> Phase 03 -> ... -> Phase N

Use Cases:

• Pipeline tasks (collect -> analyze -> generate)
• Strong dependencies between phases
• Fixed output structure

Examples: software-manual, copyright-docs

Mode 2: Autonomous (Stateless Auto-Select)

Intelligent routing model, dynamically selects execution path based on context.

---------------------------------------------------
                Orchestrator Agent
   (Read state -> Select Phase -> Execute -> Update)
---------------------------------------------------
                |
    ---------+----------+----------
    |        |          |
  Phase A   Phase B    Phase C
  (standalone)  (standalone)  (standalone)

Use Cases:

• Interactive tasks (chat, Q&A)
• No strong dependencies between phases
• Dynamic user intent response required

Examples: issue-manage, workflow-debug

Key Design Principles

1. Mode Awareness: Automatically recommend execution mode based on task characteristics
2. Skeleton Generation: Generate complete directory structure and file skeletons
3. Standards Compliance: Strictly follow specs/skill-requirements.md
4. Extensibility: Generated Skills are easy to extend and modify

---

Required Prerequisites

IMPORTANT: Before any generation operation, read the following specification documents. Generating without understanding these standards will result in non-conforming output.

Core Specifications (Mandatory Read)

Document	Purpose	Priority
specs/skill-requirements.md	Skill design spec - defines structure, naming, quality standards	P0 - Critical
specs/reference-docs-spec.md	Reference document generation spec - ensures generated Skills have proper phase-based Reference Documents with usage timing guidance	P0 - Critical

Template Files (Read Before Generation)

Document	Purpose
templates/skill-md.md	SKILL.md entry file template
templates/sequential-phase.md	Sequential Phase template
templates/autonomous-orchestrator.md	Autonomous Orchestrator template
templates/autonomous-action.md	Autonomous Action template
templates/code-analysis-action.md	Code Analysis Action template
templates/llm-action.md	LLM Action template
templates/script-template.md	Unified Script Template (Bash + Python)

Specification Documents (Read as Needed)

Document	Purpose
specs/execution-modes.md	Execution Modes Specification
specs/skill-requirements.md	Skill Requirements Specification
specs/cli-integration.md	CLI Integration Specification
specs/scripting-integration.md	Script Integration Specification

Phase Execution Guides (Reference During Execution)

Document	Purpose
phases/01-requirements-discovery.md	Collect Skill Requirements
phases/02-structure-generation.md	Generate Directory Structure
phases/03-phase-generation.md	Generate Phase Files
phases/04-specs-templates.md	Generate Specs and Templates
phases/05-validation.md	Validation and Documentation

---

Execution Flow

Input Parsing:
   └─ Convert user request to structured format (skill-name/purpose/mode)

Phase 0: Specification Study (MANDATORY - Must complete before proceeding)
   - Read specification documents
   - Load: specs/skill-requirements.md
   - Load: All templates/*.md files
   - Understand: Structure rules, naming conventions, quality standards
   - Output: Internalized requirements (in-memory, no file output)
   - Validation: MUST complete before Phase 1

Phase 1: Requirements Discovery
   - Gather skill requirements via user interaction
   - Tool: AskUserQuestion
   - Collect: Skill name, purpose, execution mode
   - Collect: Phase/Action definition
   - Collect: Tool dependencies, output format
   - Process: Generate configuration object
   - Output: skill-config.json
   - Contains: skill_name, execution_mode, phases/actions, allowed_tools

Phase 2: Structure Generation
   - Create directory structure and entry file
   - Input: skill-config.json (from Phase 1)
   - Tool: Bash
   - Execute: mkdir -p .claude/skills/{skill-name}/{phases,specs,templates,scripts}
   - Tool: Write
   - Generate: SKILL.md (entry point with architecture diagram)
   - Output: Complete directory structure

Phase 3: Phase/Action Generation
   - Decision (execution_mode check):
   - IF execution_mode === "sequential": Generate Sequential Phases
   - Read template: templates/sequential-phase.md
   - Loop: For each phase in config.sequential_config.phases
   - Generate: phases/{phase-id}.md
   - Link: Previous phase output -> Current phase input
   - Write: phases/_orchestrator.md
   - Write: workflow.json
   - Output: phases/01-{name}.md, phases/02-{name}.md, ...

   - ELSE IF execution_mode === "autonomous": Generate Orchestrator + Actions
   - Read template: templates/autonomous-orchestrator.md
   - Write: phases/state-schema.md
   - Write: phases/orchestrator.md
   - Write: specs/action-catalog.md
   - Loop: For each action in config.autonomous_config.actions
   - Read template: templates/autonomous-action.md
   - Generate: phases/actions/{action-id}.md
   - Output: phases/orchestrator.md, phases/actions/*.md

Phase 4: Specs & Templates
   - Generate domain specifications and templates
   - Input: skill-config.json (domain context)
   - Reference: [specs/reference-docs-spec.md](specs/reference-docs-spec.md) for document organization
   - Tool: Write
   - Generate: specs/{domain}-requirements.md
   - Generate: specs/quality-standards.md
   - Generate: templates/agent-base.md (if needed)
   - Output: Domain-specific documentation

Phase 5: Validation & Documentation
   - Verify completeness and generate usage guide
   - Input: All generated files from previous phases
   - Tool: Glob + Read
   - Check: Required files exist and contain proper structure
   - Tool: Write
   - Generate: README.md (usage instructions)
   - Generate: validation-report.json (completeness check)
   - Output: Final documentation
   - Close the Run: `maestro run check {run_id}` -> repair any reported gate -> if self-started, use the complete fenced `maestro run complete ... --advance` (and `maestro session complete` when the chain is terminal) from `run-mode.md`; if dispatched, return to the orchestrator. Report success only after the authoritative completion path succeeds.

Execution Protocol:

// Phase 0: Read specifications (in-memory)
Read('.claude/skills/skill-generator/specs/skill-requirements.md');
Read('.claude/skills/skill-generator/templates/*.md'); // All templates

// Phase 1: Gather requirements
const answers = AskUserQuestion({
  questions: [
    { question: "Skill name?", header: "Name", options: [...] },
    { question: "Execution mode?", header: "Mode", options: ["Sequential", "Autonomous"] }
  ]
});

const config = generateConfig(answers);
const workDir = `{run_dir}/outputs/skill-gen-${timestamp}`;
Write(`${workDir}/skill-config.json`, JSON.stringify(config));

// Phase 2: Create structure
const skillDir = `.claude/skills/${config.skill_name}`;
Bash(`mkdir -p "${skillDir}/phases" "${skillDir}/specs" "${skillDir}/templates"`);
Write(`${skillDir}/SKILL.md`, generateSkillEntry(config));

// Phase 3: Generate phases (mode-dependent)
if (config.execution_mode === 'sequential') {
  Write(`${skillDir}/phases/_orchestrator.md`, generateOrchestrator(config));
  Write(`${skillDir}/workflow.json`, generateWorkflowDef(config));
  config.sequential_config.phases.forEach(phase => {
    Write(`${skillDir}/phases/${phase.id}.md`, generatePhase(phase, config));
  });
} else {
  Write(`${skillDir}/phases/orchestrator.md`, generateAutonomousOrchestrator(config));
  Write(`${skillDir}/phases/state-schema.md`, generateStateSchema(config));
  config.autonomous_config.actions.forEach(action => {
    Write(`${skillDir}/phases/actions/${action.id}.md`, generateAction(action, config));
  });
}

// Phase 4: Generate specs
Write(`${skillDir}/specs/${config.skill_name}-requirements.md`, generateRequirements(config));
Write(`${skillDir}/specs/quality-standards.md`, generateQualityStandards(config));


// Phase 5: Validate & Document
const validation = validateStructure(skillDir);
Write(`${skillDir}/validation-report.json`, JSON.stringify(validation));
Write(`${skillDir}/README.md`, generateReadme(config, validation));

---

Reference Documents by Phase

IMPORTANT: This section demonstrates how skill-generator organizes its own reference documentation. This is the pattern that all generated Skills should emulate. See specs/reference-docs-spec.md for details.

Phase 0: Specification Study (Mandatory Prerequisites)

Specification documents that must be read before any generation operation

Document	Purpose	When to Use
specs/skill-requirements.md	Skill design specification	Understand Skill structure and naming conventions - REQUIRED
specs/reference-docs-spec.md	Reference document generation specification	Ensure Reference Documents have proper phase-based organization - REQUIRED

Phase 1: Requirements Discovery

Collect Skill requirements and configuration

Document	Purpose	When to Use
phases/01-requirements-discovery.md	Phase 1 execution guide	Understand how to collect user requirements and generate configuration
specs/skill-requirements.md	Skill requirements specification	Understand what information a Skill should contain

Phase 2: Structure Generation

Generate directory structure and entry file

Document	Purpose	When to Use
phases/02-structure-generation.md	Phase 2 execution guide	Understand how to generate directory structure
templates/skill-md.md	SKILL.md template	Learn how to generate the entry file

Phase 3: Phase/Action Generation

Generate specific phase or action files based on execution mode

Document	Purpose	When to Use
phases/03-phase-generation.md	Phase 3 execution guide	Understand Sequential vs Autonomous generation logic
templates/sequential-phase.md	Sequential Phase template	Generate phase files for Sequential mode
templates/autonomous-orchestrator.md	Orchestrator template	Generate orchestrator for Autonomous mode
templates/autonomous-action.md	Action template	Generate action files for Autonomous mode

Phase 4: Specs & Templates

Generate domain-specific specifications and templates

Document	Purpose	When to Use
phases/04-specs-templates.md	Phase 4 execution guide	Understand how to generate domain-specific documentation
specs/reference-docs-spec.md	Reference document specification	IMPORTANT: Follow this spec when generating Specs

Phase 5: Validation & Documentation

Verify results and generate final documentation

Document	Purpose	When to Use
phases/05-validation.md	Phase 5 execution guide	Understand how to verify generated Skill completeness

Debugging & Troubleshooting

Reference documents when encountering issues

Issue	Solution Document
Generated Skill missing Reference Documents	specs/reference-docs-spec.md - verify phase-based organization is followed
Reference document organization unclear	specs/reference-docs-spec.md - Core Principles section
Generated documentation does not meet quality standards	specs/skill-requirements.md

Reference & Background

Documents for deep learning and design decisions

Document	Purpose	Notes
specs/execution-modes.md	Detailed execution modes specification	Comparison and use cases for Sequential vs Autonomous
specs/cli-integration.md	CLI integration specification	How generated Skills integrate with CLI
specs/scripting-integration.md	Script integration specification	How to use scripts in Phases
templates/script-template.md	Script template	Unified Bash + Python template

---

Output Structure

Sequential Mode

.claude/skills/{skill-name}/
├── SKILL.md                        # Entry file
├── phases/
│   ├── _orchestrator.md            # Declarative orchestrator
│   ├── workflow.json               # Workflow definition
│   ├── 01-{step-one}.md           # Phase 1
│   ├── 02-{step-two}.md           # Phase 2
│   └── 03-{step-three}.md         # Phase 3
├── specs/
│   ├── {skill-name}-requirements.md
│   └── quality-standards.md
├── templates/
│   └── agent-base.md
├── scripts/
└── README.md

Autonomous Mode

.claude/skills/{skill-name}/
├── SKILL.md                        # Entry file
├── phases/
│   ├── orchestrator.md             # Orchestrator (state-driven)
│   ├── state-schema.md             # State schema definition
│   └── actions/
│       ├── action-init.md
│       ├── action-create.md
│       └── action-list.md
├── specs/
│   ├── {skill-name}-requirements.md
│   ├── action-catalog.md
│   └── quality-standards.md
├── templates/
│   ├── orchestrator-base.md
│   └── action-base.md
├── scripts/
└── README.md

---

Reference Documents by Phase

IMPORTANT: This section demonstrates how skill-generator organizes its own reference documentation. This is the pattern that all generated Skills should emulate. See specs/reference-docs-spec.md for details.

Phase 0: Specification Study (Mandatory Prerequisites)

Specification documents that must be read before any generation operation

Document	Purpose	When to Use
specs/skill-requirements.md	Skill design specification	Understand Skill structure and naming conventions - REQUIRED
specs/reference-docs-spec.md	Reference document generation specification	Ensure Reference Documents have proper phase-based organization - REQUIRED

Phase 1: Requirements Discovery

Collect Skill requirements and configuration

Document	Purpose	When to Use
phases/01-requirements-discovery.md	Phase 1 execution guide	Understand how to collect user requirements and generate configuration
specs/skill-requirements.md	Skill requirements specification	Understand what information a Skill should contain

Phase 2: Structure Generation

Generate directory structure and entry file

Document	Purpose	When to Use
phases/02-structure-generation.md	Phase 2 execution guide	Understand how to generate directory structure
templates/skill-md.md	SKILL.md template	Learn how to generate the entry file

Phase 3: Phase/Action Generation

Generate specific phase or action files based on execution mode

Document	Purpose	When to Use
phases/03-phase-generation.md	Phase 3 execution guide	Understand Sequential vs Autonomous generation logic
templates/sequential-phase.md	Sequential Phase template	Generate phase files for Sequential mode
templates/autonomous-orchestrator.md	Orchestrator template	Generate orchestrator for Autonomous mode
templates/autonomous-action.md	Action template	Generate action files for Autonomous mode

Phase 4: Specs & Templates

Generate domain-specific specifications and templates

Document	Purpose	When to Use
phases/04-specs-templates.md	Phase 4 execution guide	Understand how to generate domain-specific documentation
specs/reference-docs-spec.md	Reference document specification	IMPORTANT: Follow this spec when generating Specs

Phase 5: Validation & Documentation

Verify results and generate final documentation

Document	Purpose	When to Use
phases/05-validation.md	Phase 5 execution guide	Understand how to verify generated Skill completeness

Debugging & Troubleshooting

Reference documents when encountering issues

Issue	Solution Document
Generated Skill missing Reference Documents	specs/reference-docs-spec.md - verify phase-based organization is followed
Reference document organization unclear	specs/reference-docs-spec.md - Core Principles section
Generated documentation does not meet quality standards	specs/skill-requirements.md

Reference & Background

Documents for deep learning and design decisions

Document	Purpose	Notes
specs/execution-modes.md	Detailed execution modes specification	Comparison and use cases for Sequential vs Autonomous
specs/cli-integration.md	CLI integration specification	How generated Skills integrate with CLI
specs/scripting-integration.md	Script integration specification	How to use scripts in Phases
templates/script-template.md	Script template	Unified Bash + Python template