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.85
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 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 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 `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](specs/skill-requirements.md) | Skill design spec - defines structure, naming, quality standards | **P0 - Critical** |
| [specs/reference-docs-spec.md](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](templates/skill-md.md) | SKILL.md entry file template |
| [templates/sequential-phase.md](templates/sequential-phase.md) | Sequential Phase template |
| [templates/autonomous-orchestrator.md](templates/autonomous-orchestrator.md) | Autonomous Orchestrator template |
| [templates/autonomous-action.md](templates/autonomous-action.md) | Autonomous Action template |
| [templates/code-analysis-action.md](templates/code-analysis-action.md) | Code Analysis Action template |
| [templates/llm-action.md](templates/llm-action.md) | LLM Action template |
| [templates/script-template.md](templates/script-template.md) | Unified Script Template (Bash + Python) |

### Specification Documents (Read as Needed)

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

### Phase Execution Guides (Reference During Execution)

| Document | Purpose |
|----------|---------|
| [phases/01-requirements-discovery.md](phases/01-requirements-discovery.md) | Collect Skill Requirements |
| [phases/02-structure-generation.md](phases/02-structure-generation.md) | Generate Directory Structure |
| [phases/03-phase-generation.md](phases/03-phase-generation.md) | Generate Phase Files |
| [phases/04-specs-templates.md](phases/04-specs-templates.md) | Generate Specs and Templates |
| [phases/05-validation.md](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: 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 -> 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**:

```javascript
// 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 = 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](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](specs/skill-requirements.md) | Skill design specification | Understand Skill structure and naming conventions - **REQUIRED** |
| [specs/reference-docs-spec.md](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](phases/01-requirements-discovery.md) | Phase 1 execution guide | Understand how to collect user requirements and generate configuration |
| [specs/skill-requirements.md](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](phases/02-structure-generation.md) | Phase 2 execution guide | Understand how to generate directory structure |
| [templates/skill-md.md](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](phases/03-phase-generation.md) | Phase 3 execution guide | Understand Sequential vs Autonomous generation logic |
| [templates/sequential-phase.md](templates/sequential-phase.md) | Sequential Phase template | Generate phase files for Sequential mode |
| [templates/autonomous-orchestrator.md](templates/autonomous-orchestrator.md) | Orchestrator template | Generate orchestrator for Autonomous mode |
| [templates/autonomous-action.md](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](phases/04-specs-templates.md) | Phase 4 execution guide | Understand how to generate domain-specific documentation |
| [specs/reference-docs-spec.md](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](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](specs/reference-docs-spec.md) - verify phase-based organization is followed |
| Reference document organization unclear | [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - Core Principles section |
| Generated documentation does not meet quality standards | [specs/skill-requirements.md](specs/skill-requirements.md) |

### Reference & Background

Documents for deep learning and design decisions

| Document | Purpose | Notes |
|----------|---------|-------|
| [specs/execution-modes.md](specs/execution-modes.md) | Detailed execution modes specification | Comparison and use cases for Sequential vs Autonomous |
| [specs/cli-integration.md](specs/cli-integration.md) | CLI integration specification | How generated Skills integrate with CLI |
| [specs/scripting-integration.md](specs/scripting-integration.md) | Script integration specification | How to use scripts in Phases |
| [templates/script-template.md](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](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](specs/skill-requirements.md) | Skill design specification | Understand Skill structure and naming conventions - **REQUIRED** |
| [specs/reference-docs-spec.md](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](phases/01-requirements-discovery.md) | Phase 1 execution guide | Understand how to collect user requirements and generate configuration |
| [specs/skill-requirements.md](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](phases/02-structure-generation.md) | Phase 2 execution guide | Understand how to generate directory structure |
| [templates/skill-md.md](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](phases/03-phase-generation.md) | Phase 3 execution guide | Understand Sequential vs Autonomous generation logic |
| [templates/sequential-phase.md](templates/sequential-phase.md) | Sequential Phase template | Generate phase files for Sequential mode |
| [templates/autonomous-orchestrator.md](templates/autonomous-orchestrator.md) | Orchestrator template | Generate orchestrator for Autonomous mode |
| [templates/autonomous-action.md](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](phases/04-specs-templates.md) | Phase 4 execution guide | Understand how to generate domain-specific documentation |
| [specs/reference-docs-spec.md](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](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](specs/reference-docs-spec.md) - verify phase-based organization is followed |
| Reference document organization unclear | [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - Core Principles section |
| Generated documentation does not meet quality standards | [specs/skill-requirements.md](specs/skill-requirements.md) |

### Reference & Background

Documents for deep learning and design decisions

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