skill-generator

name	skill-generator
disable-model-invocation	true
description	Meta-skill for creating new Claude Code skills with configurable execution modes. Supports sequential (fixed order) and autonomous (stateless) phase patterns. Use for skill scaffolding, skill creation, or building new workflows. Triggers on "create skill", "new skill", "skill generator".
allowed-tools	Agent, AskUserQuestion, Read, Bash, Glob, Grep, Write
session-mode	run

<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 === ) {
  (, (config));
  (, (config));
  config...( {
    (, (phase, config));
  });
}  {
  (, (config));
  (, (config));
  config...( {
    (, (action, config));
  });
}


(, (config));
(, (config));



 validation = (skillDir);
(, .(validation));
(, (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