skill-generator

> **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/exe