| 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.83 |
| 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)
- Codebase docs: If
.workflow/codebase/ARCHITECTURE.md exists, read for project context
- Specs:
maestro load --type spec --category coding — load coding conventions
- Wiki knowledge:
maestro search "skill design optimization" --json — top 5 entries as prior context
- 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
- Mode Awareness: Automatically recommend execution mode based on task characteristics
- Skeleton Generation: Generate complete directory structure and file skeletons
- Standards Compliance: Strictly follow
specs/skill-requirements.md
- 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)
Specification Documents (Read as Needed)
Phase Execution Guides (Reference During Execution)
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:
Read('.claude/skills/skill-generator/specs/skill-requirements.md');
Read('.claude/skills/skill-generator/templates/*.md');
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));
const skillDir = `.claude/skills/${config.skill_name}`;
Bash(`mkdir -p "${skillDir}/phases" "${skillDir}/specs" "${skillDir}/templates"`);
Write(`${skillDir}/SKILL.md`, generateSkillEntry(config));
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
Phase 2: Structure Generation
Generate directory structure and entry file
Phase 3: Phase/Action Generation
Generate specific phase or action files based on execution mode
Phase 4: Specs & Templates
Generate domain-specific specifications and templates
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
Reference & Background
Documents for deep learning and design decisions
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
Phase 2: Structure Generation
Generate directory structure and entry file
Phase 3: Phase/Action Generation
Generate specific phase or action files based on execution mode
Phase 4: Specs & Templates
Generate domain-specific specifications and templates
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
Reference & Background
Documents for deep learning and design decisions
