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	["Bash","Glob","Grep","Read","Write","followup_task","interrupt_agent","list_agents","request_user_input","send_message","spawn_agent","spawn_agents_on_csv","wait_agent"]
session-mode	run
version	0.5.55
contract	{"discovery":"self-described","consumes":[],"produces":[],"gates":{"entry":[],"exit":[]}}

Agent timeout: spawn_agent 异步执行且无内置超时 — 除明确短任务外一律 spawn_agent 后立即 wait_agent({ timeout_ms: 3600000 })（上限 1 小时）阻塞等待，绝不依赖 30000 默认值；timed_out: true 且 Agent 未完成时再次 wait_agent 续等，不丢弃。批量场景使用 spawn_agents_on_csv({ max_runtime_seconds: 3600, ... })。

<required_reading> @/.maestro/workflows/run-mode.md @/.maestro/workflows/codex-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 run_id / run_dir in the birth packet, use them and do NOT call maestro run create. Otherwise self-start before Phase 1:

maestro run create skill-generator --session <YYYYMMDD-skill-generator-{topic}> --intent "<short phrase>"

Session slug is ASCII-only, ≤64 chars. Retain the returned 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 spawn_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 _shared/SKILL-DESIGN-SPEC.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
../_shared/SKILL-DESIGN-SPEC.md	Universal design spec - defines structure, naming, quality standards for all Skills	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: ../_shared/SKILL-DESIGN-SPEC.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: request_user_input
   - 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 → `maestro run complete {run_id}`. Report success only after completion.

Execution Protocol:

// Phase 0: Read specifications (in-memory)
Read('.claude/skills/_shared/SKILL-DESIGN-SPEC.md');
Read('.claude/skills/skill-generator/templates/*.md'); // All templates

// Phase 1: Gather requirements
const answers = request_user_input({
  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
../_shared/SKILL-DESIGN-SPEC.md	Universal 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	../_shared/SKILL-DESIGN-SPEC.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
../_shared/SKILL-DESIGN-SPEC.md	Universal 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	../_shared/SKILL-DESIGN-SPEC.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