skill-generator

Skill 生成器

用于创建具有可配置执行模式的新 Claude Code Skill 的元技能。

架构概览

┌─────────────────────────────────────────────────────────────────┐
│                    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)        │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

执行模式

模式 1：顺序执行（固定顺序）

传统的线性执行模型，按数字前缀顺序执行各阶段。

Phase 01 -> Phase 02 -> Phase 03 -> ... -> Phase N

适用场景：

• 流水线任务（收集 -> 分析 -> 生成）
• 阶段之间存在紧密依赖
• 输出结构固定

示例：software-manual、copyright-docs

模式 2：自主执行（无状态自动选择）

智能路由模型，根据上下文动态选择执行路径。

---------------------------------------------------
                Orchestrator Agent
   (Read state -> Select Phase -> Execute -> Update)
---------------------------------------------------
                |
    ---------+----------+----------
    |        |          |
  Phase A   Phase B    Phase C
  (standalone)  (standalone)  (standalone)

适用场景：

• 交互式任务（聊天、问答）
• 阶段之间没有紧密依赖
• 需要动态响应用户意图

示例：issue-manage、workflow-debug

关键设计原则

1. 模式感知：根据任务特征自动推荐执行模式
2. 骨架生成：生成完整的目录结构和文件骨架
3. 符合标准：严格遵循 _shared/SKILL-DESIGN-SPEC.md
4. 可扩展性：生成的 Skill 易于扩展和修改

---

必需的先决条件

重要：开始任何生成操作前，请阅读以下规范文档。在不了解这些标准的情况下生成内容，会导致输出不符合规范。

核心规范（必须阅读）

文档	用途	优先级
../_shared/SKILL-DESIGN-SPEC.md	通用设计规范——定义所有 Skill 的结构、命名和质量标准	P0 - Critical
specs/reference-docs-spec.md	参考文档生成规范——确保生成的 Skill 包含适当的基于阶段的参考文档，并提供使用时机指引	P0 - Critical

模板文件（生成前阅读）

文档	用途
templates/skill-md.md	SKILL.md 入口文件模板
templates/sequential-phase.md	顺序阶段模板
templates/autonomous-orchestrator.md	自主协调器模板
templates/autonomous-action.md	自主操作模板
templates/code-analysis-action.md	代码分析操作模板
templates/llm-action.md	LLM 操作模板
templates/script-template.md	统一脚本模板（Bash + Python）

规范文档（按需阅读）

文档	用途
specs/execution-modes.md	执行模式规范
specs/skill-requirements.md	Skill 需求规范
specs/cli-integration.md	CLI 集成规范
specs/scripting-integration.md	脚本集成规范

阶段执行指南（执行期间参考）

文档	用途
phases/01-requirements-discovery.md	收集 Skill 需求
phases/02-structure-generation.md	生成目录结构
phases/03-phase-generation.md	生成阶段文件
phases/04-specs-templates.md	生成规范和模板
phases/05-validation.md	验证和文档编写

---

执行流程

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: AskUserQuestion
   - 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

执行协议：

// 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 = AskUserQuestion({
  questions: [
    { question: "Skill name?", header: "Name", options: [...] },
    { question: "Execution mode?", header: "Mode", options: ["Sequential", "Autonomous"] }
  ]
});

const config = generateConfig(answers);
const workDir = `.workflow/.scratchpad/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));

---

按阶段划分的参考文档

重要：本节展示了 skill-generator 如何组织自身的参考文档。这是所有生成的 Skills 都应遵循的模式。详情请参阅 specs/reference-docs-spec.md。

阶段 0：规范研读（强制前置条件）

任何生成操作开始前必须阅读的规范文档

文档	用途	使用时机
../_shared/SKILL-DESIGN-SPEC.md	通用 Skill 设计规范	了解 Skill 结构和命名约定——必需
specs/reference-docs-spec.md	参考文档生成规范	确保参考文档按阶段正确组织——必需

阶段 1：需求发现

收集 Skill 需求和配置信息

文档	用途	使用时机
phases/01-requirements-discovery.md	阶段 1 执行指南	了解如何收集用户需求并生成配置
specs/skill-requirements.md	Skill 需求规范	了解 Skill 应包含哪些信息

阶段 2：结构生成

生成目录结构和入口文件

文档	用途	使用时机
phases/02-structure-generation.md	阶段 2 执行指南	了解如何生成目录结构
templates/skill-md.md	SKILL.md 模板	学习如何生成入口文件

阶段 3：阶段/操作生成

根据执行模式生成特定的阶段或操作文件

文档	用途	使用时机
phases/03-phase-generation.md	阶段 3 执行指南	了解顺序式与自主式生成逻辑之间的区别
templates/sequential-phase.md	顺序式阶段模板	为顺序式模式生成阶段文件
templates/autonomous-orchestrator.md	编排器模板	为自主式模式生成编排器
templates/autonomous-action.md	操作模板	为自主式模式生成操作文件

阶段 4：规范与模板

生成特定领域的规范和模板

文档	用途	使用时机
phases/04-specs-templates.md	阶段 4 执行指南	了解如何生成特定领域的文档
specs/reference-docs-spec.md	参考文档规范	重要：生成规范时请遵循此规范

阶段 5：验证与文档编写

验证结果并生成最终文档

文档	用途	使用时机
phases/05-validation.md	阶段 5 执行指南	了解如何验证生成的 Skill 是否完整

调试与故障排除

遇到问题时查阅相关文档

问题	解决方案文档
生成的 Skill 缺少参考文档	specs/reference-docs-spec.md - 确认是否遵循了按阶段组织的方式
参考文档的组织方式不明确	specs/reference-docs-spec.md - 核心原则部分
生成的文档未达到质量标准	../_shared/SKILL-DESIGN-SPEC.md

参考资料与背景

用于深入学习和设计决策的文档

文档	用途	备注
specs/execution-modes.md	详细的执行模式规范	对比 Sequential 与 Autonomous，并介绍适用场景
specs/cli-integration.md	CLI 集成规范	介绍生成的 Skills 如何与 CLI 集成
specs/scripting-integration.md	脚本集成规范	介绍如何在各阶段使用脚本
templates/script-template.md	脚本模板	统一的 Bash + Python 模板

---

输出结构

Sequential 模式

.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 模式

.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

---

按阶段划分的参考文档

IMPORTANT：本节展示 skill-generator 如何组织自身的参考文档。所有生成的 Skills 都应仿照此模式。详情请参阅 specs/reference-docs-spec.md。

阶段 0：规范研读（必备前置条件）

任何生成操作开始前都必须阅读的规范文档

文档	用途	使用时机
../_shared/SKILL-DESIGN-SPEC.md	通用 Skill 设计规范	了解 Skill 结构和命名约定 - REQUIRED
specs/reference-docs-spec.md	参考文档生成规范	确保参考文档按阶段妥善组织 - REQUIRED

阶段 1：需求发现

收集 Skill 需求和配置

文档	用途	使用时机
phases/01-requirements-discovery.md	阶段 1 执行指南	了解如何收集用户需求并生成配置
specs/skill-requirements.md	Skill 需求规范	了解 Skill 应包含哪些信息

阶段 2：结构生成

生成目录结构和入口文件

文档	用途	使用时机
phases/02-structure-generation.md	阶段 2 执行指南	了解如何生成目录结构
templates/skill-md.md	SKILL.md 模板	了解如何生成入口文件

阶段 3：阶段/操作生成

根据执行模式生成特定阶段或操作文件

文档	用途	使用时机
phases/03-phase-generation.md	阶段 3 执行指南	了解 Sequential 与 Autonomous 模式下的生成逻辑
templates/sequential-phase.md	Sequential 阶段模板	为 Sequential 模式生成阶段文件
templates/autonomous-orchestrator.md	编排器模板	为 Autonomous 模式生成编排器
templates/autonomous-action.md	操作模板	为 Autonomous 模式生成操作文件

阶段 4：规范与模板

生成特定领域的规范和模板

文档	用途	使用时机
phases/04-specs-templates.md	阶段 4 执行指南	了解如何生成特定领域的文档
specs/reference-docs-spec.md	参考文档规范	IMPORTANT：生成规范时请遵循此规范

阶段 5：验证与文档编写

验证结果并生成最终文档

文档	用途	使用时机
phases/05-validation.md	阶段 5 执行指南	了解如何验证生成的 Skill 是否完整

调试与故障排除

遇到问题时参考以下文档

问题	解决方案文档
生成的 Skill 缺少参考文档	specs/reference-docs-spec.md - 验证是否遵循了基于阶段的组织方式
参考文档的组织方式不明确	specs/reference-docs-spec.md - 核心原则部分
生成的文档未达到质量标准	../_shared/SKILL-DESIGN-SPEC.md

参考与背景

用于深入学习和了解设计决策的文档

文档	用途	备注
specs/execution-modes.md	详细的执行模式规范	顺序模式与自主模式的比较和使用场景
specs/cli-integration.md	CLI 集成规范	了解生成的 Skills 如何与 CLI 集成
specs/scripting-integration.md	脚本集成规范	了解如何在各阶段使用脚本
templates/script-template.md	脚本模板	统一的 Bash + Python 模板