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