skill-generator

Name: skill-generator
Rating: 8.3 (10 reviews)
Author: catlog22

by catlog221.7k0GitHub

A meta-skill that generates new Claude Code skills with configurable execution modes (sequential or autonomous). It creates complete directory structures, phase files, specifications, and templates based on user requirements. The skill follows established design patterns and includes quality control mechanisms.

Unlock Deep Analysis

Use AI to visualize the workflow and generate a realistic output preview for this skill.

Target Audience

Claude Code developers creating new skills, workflow designers, and teams establishing standardized development practices

7/10Security

Low security risk, safe to use

Clarity

Practicality

Quality

Maintainability

Innovation

Skill Generator

Meta-skill for creating new Claude Code skills with configurable execution modes.

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│  Skill Generator Architecture                                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Phase 1: Requirements    → skill-config.json                   │
│           Discovery           (name, type, mode, agents)        │
│           ↓                                                      │
│  Phase 2: Structure       → 目录结构 + 核心文件骨架              │
│           Generation                                             │
│           ↓                                                      │
│  Phase 3: Phase           → phases/*.md (根据 mode 生成)         │
│           Generation          Sequential | Autonomous            │
│           ↓                                                      │
│  Phase 4: Specs &         → specs/*.md + templates/*.md         │
│           Templates                                              │
│           ↓                                                      │
│  Phase 5: Validation      → 验证完整性 + 生成使用说明            │
│           & Documentation                                        │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Execution Modes

Mode 1: Sequential (固定顺序)

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

Phase 01 → Phase 02 → Phase 03 → ... → Phase N

适用场景:

流水线式任务（收集 → 分析 → 生成）
阶段间有强依赖关系
输出结构固定

示例: software-manual, copyright-docs

Mode 2: Autonomous (无状态自主选择)

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

┌─────────────────────────────────────────┐
│           Orchestrator Agent            │
│  (读取状态 → 选择 Phase → 执行 → 更新)  │
└───────────────┬─────────────────────────┘
                │
    ┌───────────┼───────────┐
    ↓           ↓           ↓
┌───────┐  ┌───────┐  ┌───────┐
│Phase A│  │Phase B│  │Phase C│
│(独立) │  │(独立) │  │(独立) │
└───────┘  └───────┘  └───────┘

适用场景:

交互式任务（对话、问答）
阶段间无强依赖
需要动态响应用户意图

示例: issue-manage, workflow-debug

Key Design Principles

模式感知: 根据任务特性自动推荐执行模式
骨架生成: 生成完整目录结构和文件骨架
规范遵循: 严格遵循 _shared/SKILL-DESIGN-SPEC.md
可扩展性: 生成的 Skill 易于扩展和修改

Execution Flow

┌─────────────────────────────────────────────────────────────────┐
│  Phase 1: Requirements Discovery                                 │
│  → AskUserQuestion: Skill 名称、目标、执行模式                   │
│  → Output: skill-config.json                                    │
├─────────────────────────────────────────────────────────────────┤
│  Phase 2: Structure Generation                                   │
│  → 创建目录结构: phases/, specs/, templates/, scripts/          │
│  → 生成 SKILL.md 入口文件                                        │
│  → Output: 完整目录结构                                          │
├─────────────────────────────────────────────────────────────────┤
│  Phase 3: Phase Generation                                       │
│  → Sequential: 生成 01-xx.md, 02-xx.md, ...                     │
│  → Autonomous: 生成 orchestrator.md + actions/*.md              │
│  → Output: phases/*.md                                          │
├─────────────────────────────────────────────────────────────────┤
│  Phase 4: Specs & Templates                                      │
│  → 生成领域规范: specs/{domain}-requirements.md                  │
│  → 生成质量标准: specs/quality-standards.md                      │
│  → 生成模板: templates/agent-base.md                             │
│  → Output: specs/*.md, templates/*.md                           │
├─────────────────────────────────────────────────────────────────┤
│  Phase 5: Validation & Documentation                             │
│  → 验证文件完整性                                                 │
│  → 生成 README.md 使用说明                                       │
│  → Output: 验证报告 + README.md                                  │
└─────────────────────────────────────────────────────────────────┘

Directory Setup

const skillName = config.skill_name;
const skillDir = `.claude/skills/${skillName}`;

// 创建目录结构
Bash(`mkdir -p "${skillDir}/phases"`);
Bash(`mkdir -p "${skillDir}/specs"`);
Bash(`mkdir -p "${skillDir}/templates"`);

// Autonomous 模式额外目录
if (config.execution_mode === 'autonomous') {
  Bash(`mkdir -p "${skillDir}/phases/actions"`);
}

Output Structure

Sequential Mode

.claude/skills/{skill-name}/
├── SKILL.md
├── phases/
│   ├── 01-{step-one}.md
│   ├── 02-{step-two}.md
│   └── 03-{step-three}.md
├── specs/
│   ├── {domain}-requirements.md
│   └── quality-standards.md
└── templates/
    └── agent-base.md

Autonomous Mode

.claude/skills/{skill-name}/
├── SKILL.md
├── phases/
│   ├── orchestrator.md          # 编排器：读取状态 → 选择动作
│   ├── state-schema.md          # 状态结构定义
│   └── actions/                 # 独立动作（无顺序）
│       ├── action-{a}.md
│       ├── action-{b}.md
│       └── action-{c}.md
├── specs/
│   ├── {domain}-requirements.md
│   ├── action-catalog.md        # 动作目录（描述、前置条件、效果）
│   └── quality-standards.md
└── templates/
    ├── orchestrator-base.md     # 编排器模板
    └── action-base.md           # 动作模板

Reference Documents

Document	Purpose
phases/01-requirements-discovery.md	收集 Skill 需求
phases/02-structure-generation.md	生成目录结构
phases/03-phase-generation.md	生成 Phase 文件
phases/04-specs-templates.md	生成规范和模板
phases/05-validation.md	验证和文档
specs/execution-modes.md	执行模式规范
specs/skill-requirements.md	Skill 需求规范
templates/skill-md.md	SKILL.md 模板
templates/sequential-phase.md	Sequential Phase 模板
templates/autonomous-orchestrator.md	Autonomous 编排器模板
templates/autonomous-action.md	Autonomous Action 模板
../_shared/SKILL-DESIGN-SPEC.md	通用设计规范

Referenced Files

The following files are referenced in this skill and included for context.

phases/01-requirements-discovery.md

# Phase 1: Requirements Discovery

收集新 Skill 的需求信息，生成配置文件。

## Objective

- 收集 Skill 基本信息（名称、描述、触发词）
- 确定执行模式（Sequential / Autonomous）
- 定义阶段/动作
- 配置工具依赖和输出格式

## Execution Steps

### Step 1: 基本信息收集

```javascript
const basicInfo = await AskUserQuestion({
  questions: [
    {
      question: "新 Skill 的名称是什么？（英文，小写-连字符格式，如 'api-docs'）",
      header: "Skill 名称",
      multiSelect: false,
      options: [
        { label: "自动生成", description: "根据后续描述自动生成名称" },
        { label: "手动输入", description: "现在输入自定义名称" }
      ]
    },
    {
      question: "Skill 的主要用途是什么？",
      header: "用途类型",
      multiSelect: false,
      options: [
        { label: "文档生成", description: "生成 Markdown/HTML 文档（如手册、报告）" },
        { label: "代码分析", description: "分析代码结构、质量、安全性" },
        { label: "交互管理", description: "管理 Issue、任务、工作流（CRUD 操作）" },
        { label: "数据处理", description: "ETL、格式转换、报告生成" }
      ]
    }
  ]
});

// 如果选择手动输入，进一步询问
if (basicInfo["Skill 名称"] === "手动输入") {
  // 用户会在 "Other" 中输入
}

// 根据用途类型推断描述模板
const purposeTemplates = {
  "文档生成": "Generate {type} documents from {source}",
  "代码分析": "Analyze {target} for {purpose}",
  "交互管理": "Manage {entity} with interactive operations",
  "数据处理": "Process {data} and generate {output}"
};

Step 2: 执行模式选择

const modeInfo = await AskUserQuestion({
  questions: [
    {
      question: "选择执行模式：",
      header: "执行模式",
      multiSelect: false,
      options: [
        { 
          label: "Sequential (顺序模式)", 
          description: "阶段按固定顺序执行（收集→分析→生成），适合流水线任务（推荐）" 
        },
        { 
          label: "Autonomous (自主模式)", 
          description: "动态选择执行路径，适合交互式任务（如 Issue 管理）" 
        },
        { 
          label: "Hybrid (混合模式)", 
          description: "初始化和收尾固定，中间交互灵活" 
        }
      ]
    }
  ]
});

const executionMode = modeInfo["执行模式"].includes("Sequential") ? "sequential" :
                      modeInfo["执行模式"].includes("Autonomous") ? "autonomous" : "hybrid";

Step 3: 阶段/动作定义

Sequential 模式

if (executionMode === "sequential") {
  const phaseInfo = await AskUserQuestion({
    questions: [
      {
        question: "需要多少个执行阶段？",
        header: "阶段数量",
        multiSelect: false,
        options: [
          { label: "3 阶段（简单）", description: "收集 → 处理 → 输出" },
          { label: "5 阶段（标准）", description: "收集 → 探索 → 分析 → 组装 → 验证" },
          { label: "7 阶段（完整）", description: "含并行处理、汇总、迭代优化" }
        ]
      }
    ]
  });
  
  // 根据选择生成阶段定义
  const phaseTemplates = {
    "3 阶段": [
      { id: "01-collection", name: "Data Collection" },
      { id: "02-processing", name: "Processing" },
      { id: "03-output", name: "Output Generation" }
    ],
    "5 阶段": [
      { id: "01-collection", name: "Requirements Collection" },
      { id: "02-exploration", name: "Project Exploration" },
      { id: "03-analysis", name: "Deep Analysis" },
      { id: "04-assembly", name: "Document Assembly" },
      { id: "05-validation", name: "Validation" }
    ],
    "7 阶段": [
      { id: "01-collection", name: "Requirements Collection" },
      { id: "02-exploration", name: "Project Exploration" },
      { id: "03-parallel", name: "Parallel Analysis" },
      { id: "03.5-consolidation", name: "Consolidation" },
      { id: "04-assembly", name: "Document Assembly" },
      { id: "05-refinement", name: "Iterative Refinement" },
      { id: "06-output", name: "Final Output" }
    ]
  };
}

Autonomous 模式

if (executionMode === "autonomous") {
  const actionInfo = await AskUserQuestion({
    questions: [
      {
        question: "核心动作有哪些？（可多选）",
        header: "动作定义",
        multiSelect: true,
        options: [
          { label: "初始化 (init)", description: "设置初始状态" },
          { label: "列表 (list)", description: "显示当前项目列表" },
          { label: "创建 (create)", description: "创建新项目" },
          { label: "编辑 (edit)", description: "修改现有项目" },
          { label: "删除 (delete)", description: "删除项目" },
          { label: "搜索 (search)", description: "搜索/过滤项目" }
        ]
      }
    ]
  });
}

Step 4: 工具和输出配置

const toolsInfo = await AskUserQuestion({
  questions: [
    {
      question: "需要哪些特殊工具？（基础工具已默认包含）",
      header: "工具选择",
      multiSelect: true,
      options: [
        { label: "用户交互 (AskUserQuestion)", description: "需要与用户对话" },
        { label: "Chrome 截图 (mcp__chrome__*)", description: "需要网页截图" },
        { label: "外部搜索 (mcp__exa__search)", description: "需要搜索外部信息" },
        { label: "无特殊需求", description: "仅使用基础工具" }
      ]
    },
    {
      question: "输出格式是什么？",
      header: "输出格式",
      multiSelect: false,
      options: [
        { label: "Markdown", description: "适合文档和报告" },
        { label: "HTML", description: "适合交互式文档" },
        { label: "JSON", description: "适合数据和配置" }
      ]
    }
  ]
});

Step 5: 生成配置文件

const config = {
  skill_name: skillName,
  display_name: displayName,
  description: description,
  triggers: triggers,
  execution_mode: executionMode,
  
  // 模式特定配置
  ...(executionMode === "sequential" ? {
    sequential_config: { phases: phases }
  } : {
    autonomous_config: { 
      state_schema: stateSchema,
      actions: actions,
      termination_conditions: ["user_exit", "error_limit", "task_completed"]
    }
  }),
  
  allowed_tools: [
    "Task", "Read", "Write", "Glob", "Grep", "Bash",
    ...selectedTools
  ],
  
  output: {
    format: outputFormat.toLowerCase(),
    location: `.workflow/.scratchpad/${skillName}-{timestamp}`,
    filename_pattern: `{name}-output.${outputFormat === "HTML" ? "html" : outputFormat === "JSON" ? "json" : "md"}`
  },
  
  created_at: new Date().toISOString(),
  version: "1.0.0"
};

// 写入配置文件
const workDir = `.workflow/.scratchpad/skill-gen-${timestamp}`;
Bash(`mkdir -p "${workDir}"`);
Write(`${workDir}/skill-config.json`, JSON.stringify(config, null, 2));

Output

File: skill-config.json
Location: .workflow/.scratchpad/skill-gen-{timestamp}/
Format: JSON

Next Phase

→ Phase 2: Structure Generation


### phases/02-structure-generation.md

```markdown
# Phase 2: Structure Generation

根据配置创建 Skill 目录结构和入口文件。

## Objective

- 创建标准目录结构
- 生成 SKILL.md 入口文件
- 根据执行模式创建对应的子目录

## Input

- 依赖: `skill-config.json` (Phase 1 产出)

## Execution Steps

### Step 1: 读取配置

```javascript
const config = JSON.parse(Read(`${workDir}/skill-config.json`));
const skillDir = `.claude/skills/${config.skill_name}`;

Step 2: 创建目录结构

// 基础目录
Bash(`mkdir -p "${skillDir}/phases"`);
Bash(`mkdir -p "${skillDir}/specs"`);
Bash(`mkdir -p "${skillDir}/templates"`);

// Autonomous 模式额外目录
if (config.execution_mode === 'autonomous' || config.execution_mode === 'hybrid') {
  Bash(`mkdir -p "${skillDir}/phases/actions"`);
}

// 可选: scripts 目录
if (config.needs_scripts) {
  Bash(`mkdir -p "${skillDir}/scripts"`);
}

Step 3: 生成 SKILL.md

const skillMdTemplate = `---
name: ${config.skill_name}
description: ${config.description}. Triggers on ${config.triggers.map(t => `"${t}"`).join(", ")}.
allowed-tools: ${config.allowed_tools.join(", ")}
---

# ${config.display_name}

${config.description}

## Architecture Overview

\`\`\`
${generateArchitectureDiagram(config)}
\`\`\`

## Key Design Principles

${generateDesignPrinciples(config)}

## Execution Flow

${generateExecutionFlow(config)}

## Directory Setup

\`\`\`javascript
const timestamp = new Date().toISOString().slice(0,19).replace(/[-:T]/g, '');
const workDir = \`${config.output.location.replace('{timestamp}', '${timestamp}')}\`;

Bash(\`mkdir -p "\${workDir}"\`);
${config.execution_mode === 'sequential' ? 
  `Bash(\`mkdir -p "\${workDir}/sections"\`);` : 
  `Bash(\`mkdir -p "\${workDir}/state"\`);`}
\`\`\`

## Output Structure

\`\`\`
${generateOutputStructure(config)}
\`\`\`

## Reference Documents

${generateReferenceTable(config)}
`;

Write(`${skillDir}/SKILL.md`, skillMdTemplate);

Step 4: 架构图生成函数

function generateArchitectureDiagram(config) {
  if (config.execution_mode === 'sequential') {
    return config.sequential_config.phases.map((p, i) => 
      `│  Phase ${i+1}: ${p.name.padEnd(15)} → ${p.output || 'output-' + (i+1) + '.json'}${' '.repeat(10)}│`
    ).join('\n│           ↓' + ' '.repeat(45) + '│\n');
  } else {
    return `
┌─────────────────────────────────────────────────────────────────┐
│           Orchestrator (状态驱动决策)                             │
└───────────────┬─────────────────────────────────────────────────┘
                │
    ┌───────────┼───────────┐
    ↓           ↓           ↓
${config.autonomous_config.actions.slice(0, 3).map(a => 
  `┌─────────┐  `).join('')}
${config.autonomous_config.actions.slice(0, 3).map(a => 
  `│${a.name.slice(0, 7).padEnd(7)}│  `).join('')}
${config.autonomous_config.actions.slice(0, 3).map(a => 
  `└─────────┘  `).join('')}`;
  }
}

function generateDesignPrinciples(config) {
  const common = [
    "1. **规范遵循**: 严格遵循 `_shared/SKILL-DESIGN-SPEC.md`",
    "2. **简要返回**: Agent 返回路径+摘要，避免上下文溢出"
  ];
  
  if (config.execution_mode === 'sequential') {
    return [...common,
      "3. **阶段隔离**: 每个阶段独立可测",
      "4. **链式输出**: 阶段产出作为下阶段输入"
    ].join('\n');
  } else {
    return [...common,
      "3. **状态驱动**: 显式状态管理，动态决策",
      "4. **动作独立**: 每个动作无副作用依赖"
    ].join('\n');
  }
}

function generateExecutionFlow(config) {
  if (config.execution_mode === 'sequential') {
    return '```\n' + config.sequential_config.phases.map((p, i) => 
      `├─ Phase ${i+1}: ${p.name}\n│  → Output: ${p.output || 'output.json'}`
    ).join('\n') + '\n```';
  } else {
    return `\`\`\`
┌─────────────────────────────────────────────────────────────────┐
│  Orchestrator Loop                                               │
│  ┌──────────┐     ┌──────────┐     ┌──────────┐                 │
│  │ Read     │────▶│ Select   │────▶│ Execute  │                 │
│  │ State    │     │ Action   │     │ Action   │                 │
│  └──────────┘     └──────────┘     └──────────┘                 │
│       ▲                                  │                       │
│       └──────────── Update State ◀───────┘                       │
└─────────────────────────────────────────────────────────────────┘
\`\`\``;
  }
}

function generateOutputStructure(config) {
  const base = `${config.output.location}/
├── ${config.execution_mode === 'sequential' ? 'sections/' : 'state.json'}`;
  
  if (config.execution_mode === 'sequential') {
    return base + '\n' + config.sequential_config.phases.map(p => 
      `│   └── ${p.output || 'section-' + p.id + '.md'}`
    ).join('\n') + `\n└── ${config.output.filename_pattern}`;
  } else {
    return base + `
├── actions-log.json
└── ${config.output.filename_pattern}`;
  }
}

function generateReferenceTable(config) {
  const rows = [];
  
  if (config.execution_mode === 'sequential') {
    config.sequential_config.phases.forEach(p => {
      rows.push(`| [phases/${p.id}.md](phases/${p.id}.md) | ${p.name} |`);
    });
  } else {
    rows.push(`| [phases/orchestrator.md](phases/orchestrator.md) | 编排器 |`);
    rows.push(`| [phases/state-schema.md](phases/state-schema.md) | 状态定义 |`);
    config.autonomous_config.actions.forEach(a => {
      rows.push(`| [phases/actions/${a.id}.md](phases/actions/${a.id}.md) | ${a.name} |`);
    });
  }
  
  rows.push(`| [specs/${config.skill_name}-requirements.md](specs/${config.skill_name}-requirements.md) | 领域规范 |`);
  rows.push(`| [specs/quality-standards.md](specs/quality-standards.md) | 质量标准 |`);
  
  return `| Document | Purpose |\n|----------|---------||\n` + rows.join('\n');
}

Output

Directory: .claude/skills/{skill-name}/
Files:
- SKILL.md (入口文件)
- phases/ (空目录)
- specs/ (空目录)
- templates/ (空目录)

Next Phase

→ Phase 3: Phase Generation


### phases/03-phase-generation.md

```markdown
# Phase 3: Phase Generation

根据执行模式生成 Phase 文件，包含声明式工作流编排和上下文策略支持。

## Objective

- Sequential 模式：生成顺序 Phase 文件 + **声明式编排器**
- Autonomous 模式：生成编排器和动作文件
- 支持 **文件上下文** 和 **内存上下文** 两种策略

## Input

- 依赖: `skill-config.json`, SKILL.md (Phase 1-2 产出)
- 模板: `templates/sequential-phase.md`, `templates/autonomous-*.md`

## 上下文策略 (P0 增强)

根据 `config.context_strategy` 生成不同的上下文管理代码：

| 策略 | 适用场景 | 优点 | 缺点 |
|------|----------|------|------|
| `file` | 复杂多阶段任务 | 持久化、可调试、可恢复 | IO 开销 |
| `memory` | 简单线性任务 | 速度快 | 无法恢复、调试困难 |

```javascript
const CONTEXT_STRATEGIES = {
  file: {
    read: (key) => `JSON.parse(Read(\`\${workDir}/context/${key}.json\`))`,
    write: (key, data) => `Write(\`\${workDir}/context/${key}.json\`, JSON.stringify(${data}, null, 2))`,
    init: `Bash(\`mkdir -p "\${workDir}/context"\`)`
  },
  memory: {
    read: (key) => `state.context.${key}`,
    write: (key, data) => `state.context.${key} = ${data}`,
    init: `state.context = {}`
  }
};

Execution Steps

Step 1: 读取配置和模板

const config = JSON.parse(Read(`${workDir}/skill-config.json`));
const skillDir = `.claude/skills/${config.skill_name}`;
const contextStrategy = config.context_strategy || 'file'; // 默认文件策略

// 读取模板
const skillRoot = '.claude/skills/skill-generator';

Step 2: Sequential 模式 - 生成阶段文件 + 声明式编排器

if (config.execution_mode === 'sequential') {
  const phases = config.sequential_config.phases;
  
  // ========== P0 增强: 生成声明式编排器 ==========
  const workflowOrchestrator = generateSequentialOrchestrator(config, phases);
  Write(`${skillDir}/phases/_orchestrator.md`, workflowOrchestrator);
  
  // ========== P0 增强: 生成工作流定义 ==========
  const workflowDef = generateWorkflowDefinition(config, phases);
  Write(`${skillDir}/workflow.json`, JSON.stringify(workflowDef, null, 2));
  
  // 生成各阶段文件
  for (let i = 0; i < phases.length; i++) {
    const phase = phases[i];
    const prevPhase = i > 0 ? phases[i-1] : null;
    const nextPhase = i < phases.length - 1 ? phases[i+1] : null;
    
    const content = generateSequentialPhase({
      phaseNumber: i + 1,
      phaseId: phase.id,
      phaseName: phase.name,
      phaseDescription: phase.description || `Execute ${phase.name}`,
      input: prevPhase ? prevPhase.output : "user input",
      output: phase.output,
      nextPhase: nextPhase ? nextPhase.id : null,
      config: config,
      contextStrategy: contextStrategy
    });
    
    Write(`${skillDir}/phases/${phase.id}.md`, content);
  }
}

// ========== P0 增强: 声明式工作流定义 ==========
function generateWorkflowDefinition(config, phases) {
  return {
    skill_name: config.skill_name,
    version: "1.0.0",
    execution_mode: "sequential",
    context_strategy: config.context_strategy || "file",
    
    // 声明式阶段列表 (类似 software-manual 的 agents_to_run)
    phases_to_run: phases.map(p => p.id),
    
    // 阶段配置
    phases: phases.map((p, i) => ({
      id: p.id,
      name: p.name,
      order: i + 1,
      input: i > 0 ? phases[i-1].output : null,
      output: p.output,
      // 可选的并行配置
      parallel: p.parallel || false,
      // 可选的条件执行
      condition: p.condition || null,
      // Agent 配置
      agent: p.agent || {
        type: "universal-executor",
        run_in_background: false
      }
    })),
    
    // 终止条件
    termination: {
      on_success: "all_phases_completed",
      on_error: "stop_and_report",
      max_retries: 3
    }
  };
}

// ========== P0 增强: 声明式编排器 ==========
function generateSequentialOrchestrator(config, phases) {
  return `# Sequential Orchestrator

声明式工作流编排器，按 \`workflow.json\` 定义顺序执行阶段。

## 工作流定义

\`\`\`javascript
const workflow = JSON.parse(Read(\`\${skillDir}/workflow.json\`));
\`\`\`

## 编排逻辑

\`\`\`javascript
async function runSequentialWorkflow(workDir) {
  const workflow = JSON.parse(Read(\`\${skillDir}/workflow.json\`));
  const contextStrategy = workflow.context_strategy;
  
  // 初始化上下文
  ${config.context_strategy === 'file' ? 
    `Bash(\`mkdir -p "\${workDir}/context"\`);` :
    `const state = { context: {} };`}
  
  // 执行状态追踪
  const execution = {
    started_at: new Date().toISOString(),
    phases_completed: [],
    current_phase: null,
    errors: []
  };
  
  Write(\`\${workDir}/execution-state.json\`, JSON.stringify(execution, null, 2));
  
  // 按声明顺序执行阶段
  for (const phaseId of workflow.phases_to_run) {
    const phaseConfig = workflow.phases.find(p => p.id === phaseId);
    
    // 更新执行状态
    execution.current_phase = phaseId;
    Write(\`\${workDir}/execution-state.json\`, JSON.stringify(execution, null, 2));
    
    console.log(\`[Orchestrator] Executing: \${phaseId}\`);
    
    try {
      // 检查条件执行
      if (phaseConfig.condition) {
        const shouldRun = evaluateCondition(phaseConfig.condition, execution);
        if (!shouldRun) {
          console.log(\`[Orchestrator] Skipping \${phaseId} (condition not met)\`);
          continue;
        }
      }
      
      // 执行阶段
      const result = await executePhase(phaseId, phaseConfig, workDir);
      
      // 记录完成
      execution.phases_completed.push({
        id: phaseId,
        completed_at: new Date().toISOString(),
        output: phaseConfig.output
      });
      
    } catch (error) {
      execution.errors.push({
        phase: phaseId,
        message: error.message,
        timestamp: new Date().toISOString()
      });
      
      // 错误处理策略
      if (workflow.termination.on_error === 'stop_and_report') {
        console.error(\`[Orchestrator] Failed at \${phaseId}: \${error.message}\`);
        break;
      }
    }
    
    Write(\`\${workDir}/execution-state.json\`, JSON.stringify(execution, null, 2));
  }
  
  // 完成
  execution.current_phase = null;
  execution.completed_at = new Date().toISOString();
  Write(\`\${workDir}/execution-state.json\`, JSON.stringify(execution, null, 2));
  
  return execution;
}

async function executePhase(phaseId, phaseConfig, workDir) {
  const phasePrompt = Read(\`\${skillDir}/phases/\${phaseId}.md\`);
  
  // 使用 Task 调用 Agent
  const result = await Task({
    subagent_type: phaseConfig.agent?.type || 'universal-executor',
    run_in_background: phaseConfig.agent?.run_in_background || false,
    prompt: \`
[PHASE] \${phaseId}
[WORK_DIR] \${workDir}
[INPUT] \${phaseConfig.input ? \`\${workDir}/\${phaseConfig.input}\` : 'None'}
[OUTPUT] \${workDir}/\${phaseConfig.output}

\${phasePrompt}
\`
  });
  
  return JSON.parse(result);
}
\`\`\`

## 阶段执行计划

| Order | Phase | Input | Output | Agent |
|-------|-------|-------|--------|-------|
${phases.map((p, i) => 
  `| ${i+1} | ${p.id} | ${i > 0 ? phases[i-1].output : '-'} | ${p.output} | ${p.agent?.type || 'universal-executor'} |`
).join('\n')}

## 错误恢复

\`\`\`javascript
// 从指定阶段恢复执行
async function resumeFromPhase(phaseId, workDir) {
  const workflow = JSON.parse(Read(\`\${skillDir}/workflow.json\`));
  const startIndex = workflow.phases_to_run.indexOf(phaseId);
  
  if (startIndex === -1) {
    throw new Error(\`Phase not found: \${phaseId}\`);
  }
  
  // 从指定阶段开始执行
  const remainingPhases = workflow.phases_to_run.slice(startIndex);
  // ...继续执行
}
\`\`\`
`;
}

// 生成阶段文件（增强上下文策略支持）
function generateSequentialPhase(params) {
  const contextCode = params.contextStrategy === 'file' ? {
    readPrev: `const prevOutput = JSON.parse(Read(\`\${workDir}/${params.input}\`));`,
    writeResult: `Write(\`\${workDir}/${params.output}\`, JSON.stringify(result, null, 2));`,
    readContext: (key) => `JSON.parse(Read(\`\${workDir}/context/${key}.json\`))`,
    writeContext: (key) => `Write(\`\${workDir}/context/${key}.json\`, JSON.stringify(data, null, 2))`
  } : {
    readPrev: `const prevOutput = state.context.prevPhaseOutput;`,
    writeResult: `state.context.${params.phaseId.replace(/-/g, '_')}_output = result;`,
    readContext: (key) => `state.context.${key}`,
    writeContext: (key) => `state.context.${key} = data`
  };

  return `# Phase ${params.phaseNumber}: ${params.phaseName}

${params.phaseDescription}

## Objective

- 主要目标描述
- 具体任务列表

## Input

- 依赖: \`${params.input}\`
- 配置: \`{workDir}/skill-config.json\`
- 上下文策略: \`${params.contextStrategy}\`

## Execution Steps

### Step 1: 读取输入

\`\`\`javascript
// 上下文策略: ${params.contextStrategy}
${params.phaseNumber > 1 ? contextCode.readPrev : '// 首阶段，直接从配置开始'}
\`\`\`

### Step 2: 核心处理

\`\`\`javascript
// TODO: 实现核心逻辑
const result = {
  status: 'completed',
  data: {
    // 处理结果
  },
  metadata: {
    phase: '${params.phaseId}',
    timestamp: new Date().toISOString()
  }
};
\`\`\`

### Step 3: 输出结果

\`\`\`javascript
// 写入阶段产出 (上下文策略: ${params.contextStrategy})
${contextCode.writeResult}

// 返回简要信息给编排器
return {
  status: 'completed',
  output_file: '${params.output}',
  summary: '阶段 ${params.phaseNumber} 完成'
};
\`\`\`

## Output

- **File**: \`${params.output}\`
- **Format**: ${params.output.endsWith('.json') ? 'JSON' : 'Markdown'}
- **Context Strategy**: ${params.contextStrategy}

## Quality Checklist

- [ ] 输入数据验证通过
- [ ] 核心逻辑执行成功
- [ ] 输出格式正确
- [ ] 上下文正确保存

${params.nextPhase ? 
  `## Next Phase\n\n→ [Phase ${params.phaseNumber + 1}: ${params.nextPhase}](${params.nextPhase}.md)` : 
  `## Completion\n\n此为最后阶段，输出最终产物。`}
`;
}

Step 3: Autonomous 模式 - 生成编排器 (增强版)

if (config.execution_mode === 'autonomous' || config.execution_mode === 'hybrid') {
  const contextStrategy = config.context_strategy || 'file';
  
  // 生成状态 Schema (增强文件策略支持)
  const stateSchema = generateStateSchema(config, contextStrategy);
  Write(`${skillDir}/phases/state-schema.md`, stateSchema);
  
  // 生成编排器 (增强版)
  const orchestrator = generateEnhancedOrchestrator(config, contextStrategy);
  Write(`${skillDir}/phases/orchestrator.md`, orchestrator);
  
  // 生成动作目录
  const actionCatalog = generateActionCatalog(config);
  Write(`${skillDir}/specs/action-catalog.md`, actionCatalog);
  
  // 生成动作文件
  for (const action of config.autonomous_config.actions) {
    const actionContent = generateEnhancedAction(action, config, contextStrategy);
    Write(`${skillDir}/phases/actions/${action.id}.md`, actionContent);
  }
}

// 增强版编排器生成
function generateEnhancedOrchestrator(config, contextStrategy) {
  const actions = config.autonomous_config.actions;
  
  return `# Orchestrator (Enhanced)

增强版编排器，支持声明式动作调度和文件上下文策略。

## 配置

- **上下文策略**: ${contextStrategy}
- **终止条件**: ${config.autonomous_config.termination_conditions?.join(', ') || 'task_completed'}

## 声明式动作目录

\`\`\`javascript
const ACTION_CATALOG = ${JSON.stringify(actions.map(a => ({
  id: a.id,
  name: a.name,
  preconditions: a.preconditions || [],
  effects: a.effects || [],
  priority: a.priority || 0
})), null, 2)};
\`\`\`

## 上下文管理 (${contextStrategy} 策略)

\`\`\`javascript
const ContextManager = {
  ${contextStrategy === 'file' ? `
  // 文件策略: 持久化到 .scratchpad
  init: (workDir) => {
    Bash(\`mkdir -p "\${workDir}/context"\`);
    Write(\`\${workDir}/state.json\`, JSON.stringify(initialState, null, 2));
  },
  
  readState: (workDir) => JSON.parse(Read(\`\${workDir}/state.json\`)),
  
  writeState: (workDir, state) => {
    state.updated_at = new Date().toISOString();
    Write(\`\${workDir}/state.json\`, JSON.stringify(state, null, 2));
  },
  
  readContext: (workDir, key) => {
    try {
      return JSON.parse(Read(\`\${workDir}/context/\${key}.json\`));
    } catch { return null; }
  },
  
  writeContext: (workDir, key, data) => {
    Write(\`\${workDir}/context/\${key}.json\`, JSON.stringify(data, null, 2));
  }` : `
  // 内存策略: 仅在运行时保持
  state: null,
  context: {},
  
  init: (workDir) => {
    ContextManager.state = { ...initialState };
    ContextManager.context = {};
  },
  
  readState: () => ContextManager.state,
  
  writeState: (workDir, state) => {
    state.updated_at = new Date().toISOString();
    ContextManager.state = state;
  },
  
  readContext: (workDir, key) => ContextManager.context[key],
  
  writeContext: (workDir, key, data) => {
    ContextManager.context[key] = data;
  }`}
};
\`\`\`

## 决策逻辑

\`\`\`javascript
function selectNextAction(state) {
  // 1. 终止条件检查
${config.autonomous_config.termination_conditions?.map(c => 
  `  if (${getTerminationCheck(c)}) return null;`
).join('\n') || '  if (state.status === "completed") return null;'}
  
  // 2. 错误限制检查
  if (state.error_count >= 3) return 'action-abort';
  
  // 3. 按优先级选择满足前置条件的动作
  const availableActions = ACTION_CATALOG
    .filter(a => checkPreconditions(a.preconditions, state))
    .filter(a => !state.completed_actions.includes(a.id))
    .sort((a, b) => b.priority - a.priority);
  
  if (availableActions.length > 0) {
    return availableActions[0].id;
  }
  
  // 4. 默认完成
  return 'action-complete';
}

function checkPreconditions(conditions, state) {
  if (!conditions || conditions.length === 0) return true;
  return conditions.every(cond => {
    // 支持多种条件格式
    if (cond.includes('===')) {
      const [left, right] = cond.split('===').map(s => s.trim());
      return eval(\`state.\${left}\`) === eval(right);
    }
    return state[cond] === true;
  });
}
\`\`\`

## 执行循环 (增强版)

\`\`\`javascript
async function runOrchestrator(workDir) {
  console.log('=== Orchestrator Started ===');
  console.log(\`Context Strategy: ${contextStrategy}\`);
  
  // 初始化
  ContextManager.init(workDir);
  
  let iteration = 0;
  const MAX_ITERATIONS = 100;
  
  while (iteration < MAX_ITERATIONS) {
    iteration++;
    
    // 1. 读取状态
    const state = ContextManager.readState(workDir);
    console.log(\`[Iteration \${iteration}] Status: \${state.status}, Completed: \${state.completed_actions.length}\`);
    
    // 2. 选择动作
    const actionId = selectNextAction(state);
    
    if (!actionId) {
      console.log('=== All actions completed ===');
      state.status = 'completed';
      ContextManager.writeState(workDir, state);
      break;
    }
    
    console.log(\`[Iteration \${iteration}] Executing: \${actionId}\`);
    
    // 3. 更新当前动作
    state.current_action = actionId;
    ContextManager.writeState(workDir, state);
    
    // 4. 执行动作
    try {
      const actionPrompt = Read(\`\${skillDir}/phases/actions/\${actionId}.md\`);
      
      const result = await Task({
        subagent_type: 'universal-executor',
        run_in_background: false,
        prompt: \`
[STATE]
\${JSON.stringify(state, null, 2)}

[WORK_DIR]
\${workDir}

[CONTEXT_STRATEGY]
${contextStrategy}

[ACTION]
\${actionPrompt}

[RETURN FORMAT]
Return JSON: { "status": "completed"|"failed", "stateUpdates": {...}, "summary": "..." }
\`
      });
      
      const actionResult = JSON.parse(result);
      
      // 5. 更新状态
      state.completed_actions.push(actionId);
      state.current_action = null;
      Object.assign(state, actionResult.stateUpdates || {});
      
      console.log(\`[Iteration \${iteration}] Completed: \${actionResult.summary || actionId}\`);
      
    } catch (error) {
      console.error(\`[Iteration \${iteration}] Error: \${error.message}\`);
      state.errors.push({
        action: actionId,
        message: error.message,
        timestamp: new Date().toISOString()
      });
      state.error_count++;
      state.current_action = null;
    }
    
    ContextManager.writeState(workDir, state);
  }
  
  console.log('=== Orchestrator Finished ===');
  return ContextManager.readState(workDir);
}
\`\`\`

## 动作目录

| Action | Priority | Preconditions | Effects |
|--------|----------|---------------|---------|
${actions.map(a => 
  `| [${a.id}](actions/${a.id}.md) | ${a.priority || 0} | ${a.preconditions?.join(', ') || '-'} | ${a.effects?.join(', ') || '-'} |`
).join('\n')}

## 调试与恢复

\`\`\`javascript
// 从特定状态恢复
async function resumeFromState(workDir) {
  const state = ContextManager.readState(workDir);
  console.log(\`Resuming from: \${state.current_action || 'start'}\`);
  console.log(\`Completed actions: \${state.completed_actions.join(', ')}\`);
  return runOrchestrator(workDir);
}

// 重试失败的动作
async function retryFailedAction(workDir) {
  const state = ContextManager.readState(workDir);
  if (state.errors.length > 0) {
    const lastError = state.errors[state.errors.length - 1];
    console.log(\`Retrying: \${lastError.action}\`);
    state.error_count = Math.max(0, state.error_count - 1);
    ContextManager.writeState(workDir, state);
    return runOrchestrator(workDir);
  }
}
\`\`\`
`;
}

// 增强版动作生成
function generateEnhancedAction(action, config, contextStrategy) {
  return `# Action: ${action.name}

${action.description || '执行 ' + action.name + ' 操作'}

## Purpose

${action.description || 'TODO: 描述此动作的目的'}

## Preconditions

${action.preconditions?.map(p => `- [ ] \`${p}\``).join('\n') || '- [ ] 无特殊前置条件'}

## Context Access (${contextStrategy} 策略)

\`\`\`javascript
// 读取共享上下文
${contextStrategy === 'file' ?
  `const sharedData = JSON.parse(Read(\`\${workDir}/context/shared.json\`));` :
  `const sharedData = state.context.shared || {};`}

// 写入共享上下文
${contextStrategy === 'file' ?
  `Write(\`\${workDir}/context/shared.json\`, JSON.stringify(updatedData, null, 2));` :
  `state.context.shared = updatedData;`}
\`\`\`

## Execution

\`\`\`javascript
async function execute(state, workDir) {
  // 1. 读取必要数据
  ${contextStrategy === 'file' ?
    `const input = JSON.parse(Read(\`\${workDir}/context/input.json\`));` :
    `const input = state.context.input || {};`}
  
  // 2. 执行核心逻辑
  // TODO: 实现动作逻辑
  const result = {
    // 处理结果
  };
  
  // 3. 保存结果 (${contextStrategy} 策略)
  ${contextStrategy === 'file' ?
    `Write(\`\${workDir}/context/${action.id.replace(/-/g, '_')}_result.json\`, JSON.stringify(result, null, 2));` :
    `// 结果通过 stateUpdates 返回`}
  
  // 4. 返回状态更新
  return {
    status: 'completed',
    stateUpdates: {
      completed_actions: [...state.completed_actions, '${action.id}'],
      ${contextStrategy === 'memory' ? `context: { ...state.context, ${action.id.replace(/-/g, '_')}_result: result }` : '// 文件策略：结果已保存到文件'}
    },
    summary: '${action.name} 完成'
  };
}
\`\`\`

## State Updates

\`\`\`javascript
return {
  status: 'completed',
  stateUpdates: {
    completed_actions: [...state.completed_actions, '${action.id}'],
${action.effects?.map(e => `    // Effect: ${e}`).join('\n') || '    // 无额外效果'}
  }
};
\`\`\`

## Error Handling

| 错误类型 | 处理方式 |
|----------|----------|
| 数据验证失败 | 返回错误，不更新状态 |
| 执行异常 | 记录错误，增加 error_count |
| 上下文读取失败 | 使用默认值或跳过 |

## Next Actions (Hints)

- 成功: 由编排器根据 \`ACTION_CATALOG\` 优先级决定
- 失败: 重试或 \`action-abort\`
`;
}

// 生成动作目录
function generateActionCatalog(config) {
  const actions = config.autonomous_config.actions;
  
  return `# Action Catalog

${config.display_name} 的可用动作目录（声明式）。

## 动作定义

\`\`\`json
${JSON.stringify(actions.map(a => ({
  id: a.id,
  name: a.name,
  description: a.description,
  preconditions: a.preconditions || [],
  effects: a.effects || [],
  priority: a.priority || 0
})), null, 2)}
\`\`\`

## 动作依赖图

\`\`\`mermaid
graph TD
${actions.map((a, i) => {
  const deps = a.preconditions?.filter(p => p.startsWith('completed_actions.includes'))
    .map(p => p.match(/'([^']+)'/)?.[1])
    .filter(Boolean) || [];
  
  if (deps.length === 0 && i === 0) {
    return `    START((Start)) --> ${a.id.replace(/-/g, '_')}[${a.name}]`;
  } else if (deps.length > 0) {
    return deps.map(d => `    ${d.replace(/-/g, '_')} --> ${a.id.replace(/-/g, '_')}[${a.name}]`).join('\n');
  }
  return '';
}).filter(Boolean).join('\n')}
    ${actions[actions.length-1]?.id.replace(/-/g, '_') || 'last'} --> END((End))
\`\`\`

## 选择优先级

| Priority | Action | Description |
|----------|--------|-------------|
${actions.sort((a, b) => (b.priority || 0) - (a.priority || 0)).map(a => 
  `| ${a.priority || 0} | ${a.id} | ${a.description || a.name} |`
).join('\n')}
`;
}

Step 4: 辅助函数

function toPascalCase(str) {
  return str.split('-').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join('');
}

function getDefaultValue(type) {
  if (type.endsWith('[]')) return '[]';
  if (type === 'number') return '0';
  if (type === 'boolean') return 'false';
  if (type === 'string') return '""';
  return '{}';
}

function getTerminationCheck(condition) {
  const checks = {
    'user_exit': 'state.status === "user_exit"',
    'error_limit': 'state.error_count >= 3',
    'task_completed': 'state.status === "completed"',
    'max_iterations': 'iteration >= MAX_ITERATIONS'
  };
  return checks[condition] || `state.${condition}`;
}

function getPreconditionCheck(action) {
  if (!action.preconditions?.length) return 'true';
  return action.preconditions.map(p => `state.${p}`).join(' && ');
}

Output

Sequential 模式

phases/_orchestrator.md (声明式编排器)
workflow.json (工作流定义)
phases/01-{step}.md, 02-{step}.md, ...

Autonomous 模式

phases/orchestrator.md (增强版编排器)
phases/state-schema.md
specs/action-catalog.md (声明式动作目录)
phases/actions/action-{name}.md (多个)

Next Phase

→ Phase 4: Specs & Templates


### phases/04-specs-templates.md

```markdown
# Phase 4: Specs & Templates Generation

生成规范文件和模板文件。

## Objective

- 生成领域规范 (`specs/{domain}-requirements.md`)
- 生成质量标准 (`specs/quality-standards.md`)
- 生成 Agent 模板 (`templates/agent-base.md`)
- Autonomous 模式额外生成动作目录 (`specs/action-catalog.md`)

## Input

- 依赖: `skill-config.json`, SKILL.md, phases/*.md

## Execution Steps

### Step 1: 生成领域规范

```javascript
const config = JSON.parse(Read(`${workDir}/skill-config.json`));
const skillDir = `.claude/skills/${config.skill_name}`;

const domainRequirements = `# ${config.display_name} Requirements

${config.description}

## When to Use

| Phase | Usage | Reference |
|-------|-------|-----------|
${config.execution_mode === 'sequential' ? 
  config.sequential_config.phases.map((p, i) => 
    `| Phase ${i+1} | ${p.name} | ${p.id}.md |`
  ).join('\n') :
  `| Orchestrator | 动作选择 | orchestrator.md |
| Actions | 动作执行 | actions/*.md |`}

---

## Domain Requirements

### 功能要求

- [ ] 要求1: TODO
- [ ] 要求2: TODO
- [ ] 要求3: TODO

### 输出要求

- [ ] 格式: ${config.output.format}
- [ ] 位置: ${config.output.location}
- [ ] 命名: ${config.output.filename_pattern}

### 质量要求

- [ ] 完整性: 所有必需内容存在
- [ ] 一致性: 术语和格式统一
- [ ] 准确性: 内容基于实际分析

## Validation Function

\`\`\`javascript
function validate${toPascalCase(config.skill_name)}(output) {
  const checks = [
    // TODO: 添加验证规则
    { name: "格式正确", pass: output.format === "${config.output.format}" },
    { name: "内容完整", pass: output.content?.length > 0 }
  ];
  
  return {
    passed: checks.filter(c => c.pass).length,
    total: checks.length,
    details: checks
  };
}
\`\`\`

## Error Handling

| Error | Recovery |
|-------|----------|
| 输入数据缺失 | 返回明确错误信息 |
| 处理超时 | 缩小范围，重试 |
| 输出验证失败 | 记录问题，人工审核 |
`;

Write(`${skillDir}/specs/${config.skill_name}-requirements.md`, domainRequirements);

Step 2: 生成质量标准

const qualityStandards = `# Quality Standards

${config.display_name} 的质量评估标准。

## Quality Dimensions

### 1. Completeness (完整性) - 25%

| 要求 | 权重 | 检查方式 |
|------|------|----------|
| 所有必需输出存在 | 10 | 文件检查 |
| 内容覆盖完整 | 10 | 内容分析 |
| 无占位符残留 | 5 | 文本搜索 |

### 2. Consistency (一致性) - 25%

| 方面 | 检查 |
|------|------|
| 术语 | 同一概念使用相同术语 |
| 格式 | 标题层级、代码块格式一致 |
| 风格 | 语气和表达方式统一 |

### 3. Accuracy (准确性) - 25%

| 要求 | 说明 |
|------|------|
| 数据正确 | 引用和数据无错误 |
| 逻辑正确 | 流程和关系描述准确 |
| 代码正确 | 代码示例可运行 |

### 4. Usability (可用性) - 25%

| 指标 | 目标 |
|------|------|
| 可读性 | 结构清晰，易于理解 |
| 可导航 | 目录和链接正确 |
| 可操作 | 步骤明确，可执行 |

## Quality Gates

| Gate | Threshold | Action |
|------|-----------|--------|
| Pass | ≥ 80% | 输出最终产物 |
| Review | 60-79% | 处理警告后继续 |
| Fail | < 60% | 必须修复 |

## Issue Classification

### Errors (Must Fix)

- 必需输出缺失
- 数据错误
- 代码不可运行

### Warnings (Should Fix)

- 格式不一致
- 内容深度不足
- 缺少示例

### Info (Nice to Have)

- 优化建议
- 增强机会

## Automated Checks

\`\`\`javascript
function runQualityChecks(workDir) {
  const results = {
    completeness: checkCompleteness(workDir),
    consistency: checkConsistency(workDir),
    accuracy: checkAccuracy(workDir),
    usability: checkUsability(workDir)
  };

  results.overall = (
    results.completeness * 0.25 +
    results.consistency * 0.25 +
    results.accuracy * 0.25 +
    results.usability * 0.25
  );

  return {
    score: results.overall,
    gate: results.overall >= 80 ? 'pass' : 
          results.overall >= 60 ? 'review' : 'fail',
    details: results
  };
}
\`\`\`
`;

Write(`${skillDir}/specs/quality-standards.md`, qualityStandards);

Step 3: 生成 Agent 模板

const agentBase = `# Agent Base Template

${config.display_name} 的 Agent 基础模板。

## 通用 Prompt 结构

\`\`\`
[ROLE] 你是{角色}，专注于{职责}。

[PROJECT CONTEXT]
Skill: ${config.skill_name}
目标: ${config.description}

[TASK]
{任务描述}
- 输出: {output_path}
- 格式: ${config.output.format}

[CONSTRAINTS]
- 约束1
- 约束2

[OUTPUT_FORMAT]
1. 执行任务
2. 返回 JSON 简要信息

[QUALITY_CHECKLIST]
- [ ] 输出格式正确
- [ ] 内容完整无遗漏
- [ ] 无占位符残留
\`\`\`

## 变量说明

| 变量 | 来源 | 示例 |
|------|------|------|
| {workDir} | 运行时 | .workflow/.scratchpad/${config.skill_name}-xxx |
| {output_path} | 配置 | ${config.output.location}/${config.output.filename_pattern} |

## 返回格式

\`\`\`typescript
interface AgentReturn {
  status: "completed" | "partial" | "failed";
  output_file: string;
  summary: string;  // Max 50 chars
  stats?: {
    items_processed?: number;
    errors?: number;
  };
}
\`\`\`

## 角色定义参考

${config.execution_mode === 'sequential' ?
  config.sequential_config.phases.map((p, i) => 
    `- **Phase ${i+1} Agent**: ${p.name} 专家`
  ).join('\n') :
  config.autonomous_config.actions.map(a => 
    `- **${a.name} Agent**: ${a.description || a.name + ' 执行者'}`
  ).join('\n')}
`;

Write(`${skillDir}/templates/agent-base.md`, agentBase);

Step 4: Autonomous 模式 - 动作目录

if (config.execution_mode === 'autonomous' || config.execution_mode === 'hybrid') {
  const actionCatalog = `# Action Catalog

${config.display_name} 的可用动作目录。

## Available Actions

| Action | Purpose | Preconditions | Effects |
|--------|---------|---------------|---------|
${config.autonomous_config.actions.map(a => 
  `| [${a.id}](../phases/actions/${a.id}.md) | ${a.description || a.name} | ${a.preconditions?.join(', ') || '-'} | ${a.effects?.join(', ') || '-'} |`
).join('\n')}

## Action Dependencies

\`\`\`mermaid
graph TD
${config.autonomous_config.actions.map((a, i, arr) => {
  if (i === 0) return `    ${a.id.replace(/-/g, '_')}[${a.name}]`;
  const prev = arr[i-1];
  return `    ${prev.id.replace(/-/g, '_')} --> ${a.id.replace(/-/g, '_')}[${a.name}]`;
}).join('\n')}
\`\`\`

## State Transitions

| From State | Action | To State |
|------------|--------|----------|
| pending | action-init | running |
${config.autonomous_config.actions.slice(1).map(a => 
  `| running | ${a.id} | running |`
).join('\n')}
| running | action-complete | completed |
| running | action-abort | failed |

## Selection Priority

当多个动作的前置条件都满足时，按以下优先级选择：

${config.autonomous_config.actions.map((a, i) => 
  `${i + 1}. \`${a.id}\` - ${a.name}`
).join('\n')}
`;

  Write(`${skillDir}/specs/action-catalog.md`, actionCatalog);
}

Step 5: 辅助函数

function toPascalCase(str) {
  return str.split('-').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join('');
}

Output

specs/{skill-name}-requirements.md - 领域规范
specs/quality-standards.md - 质量标准
specs/action-catalog.md - 动作目录 (Autonomous 模式)
templates/agent-base.md - Agent 模板

Next Phase

→ Phase 5: Validation


### phases/05-validation.md

```markdown
# Phase 5: Validation & Documentation

验证生成的 Skill 完整性并生成使用说明。

## Objective

- 验证所有必需文件存在
- 检查文件内容完整性
- 生成 README.md 使用说明
- 输出验证报告

## Input

- 依赖: 所有前序阶段产出
- 生成的 Skill 目录

## Execution Steps

### Step 1: 文件完整性检查

```javascript
const config = JSON.parse(Read(`${workDir}/skill-config.json`));
const skillDir = `.claude/skills/${config.skill_name}`;

const requiredFiles = {
  common: [
    'SKILL.md',
    `specs/${config.skill_name}-requirements.md`,
    'specs/quality-standards.md',
    'templates/agent-base.md'
  ],
  sequential: config.sequential_config?.phases?.map(p => `phases/${p.id}.md`) || [],
  autonomous: [
    'phases/orchestrator.md',
    'phases/state-schema.md',
    'specs/action-catalog.md',
    ...(config.autonomous_config?.actions?.map(a => `phases/actions/${a.id}.md`) || [])
  ]
};

const filesToCheck = [
  ...requiredFiles.common,
  ...(config.execution_mode === 'sequential' ? requiredFiles.sequential : requiredFiles.autonomous)
];

const fileCheckResults = filesToCheck.map(file => {
  const fullPath = `${skillDir}/${file}`;
  try {
    const content = Read(fullPath);
    return {
      file: file,
      exists: true,
      size: content.length,
      hasContent: content.length > 100,
      hasTodo: content.includes('TODO')
    };
  } catch (e) {
    return {
      file: file,
      exists: false,
      size: 0,
      hasContent: false,
      hasTodo: false
    };
  }
});

Step 2: 内容质量检查

const contentChecks = [];

// 检查 SKILL.md
const skillMd = Read(`${skillDir}/SKILL.md`);
contentChecks.push({
  file: 'SKILL.md',
  checks: [
    { name: 'Front Matter', pass: skillMd.startsWith('---') },
    { name: 'Architecture', pass: skillMd.includes('## Architecture') },
    { name: 'Execution Flow', pass: skillMd.includes('## Execution Flow') },
    { name: 'References', pass: skillMd.includes('## Reference Documents') }
  ]
});

// 检查 Phase 文件
const phaseFiles = Glob(`${skillDir}/phases/*.md`);
for (const phaseFile of phaseFiles) {
  if (phaseFile.includes('/actions/')) continue; // 单独检查
  
  const content = Read(phaseFile);
  contentChecks.push({
    file: phaseFile.replace(skillDir + '/', ''),
    checks: [
      { name: 'Objective', pass: content.includes('## Objective') },
      { name: 'Execution', pass: content.includes('## Execution') || content.includes('## Execution Steps') },
      { name: 'Output', pass: content.includes('## Output') },
      { name: 'Code Blocks', pass: content.includes('```') }
    ]
  });
}

// 检查 Specs 文件
const specFiles = Glob(`${skillDir}/specs/*.md`);
for (const specFile of specFiles) {
  const content = Read(specFile);
  contentChecks.push({
    file: specFile.replace(skillDir + '/', ''),
    checks: [
      { name: 'Has Content', pass: content.length > 200 },
      { name: 'Has Structure', pass: content.includes('##') },
      { name: 'No Empty Sections', pass: !content.match(/##[^#]+\n\n##/) }
    ]
  });
}

Step 3: 生成验证报告

const report = {
  skill_name: config.skill_name,
  execution_mode: config.execution_mode,
  generated_at: new Date().toISOString(),
  
  file_checks: {
    total: fileCheckResults.length,
    existing: fileCheckResults.filter(f => f.exists).length,
    with_content: fileCheckResults.filter(f => f.hasContent).length,
    with_todos: fileCheckResults.filter(f => f.hasTodo).length,
    details: fileCheckResults
  },
  
  content_checks: {
    files_checked: contentChecks.length,
    all_passed: contentChecks.every(c => c.checks.every(ch => ch.pass)),
    details: contentChecks
  },
  
  summary: {
    status: calculateOverallStatus(fileCheckResults, contentChecks),
    issues: collectIssues(fileCheckResults, contentChecks),
    recommendations: generateRecommendations(fileCheckResults, contentChecks)
  }
};

Write(`${workDir}/validation-report.json`, JSON.stringify(report, null, 2));

function calculateOverallStatus(fileResults, contentResults) {
  const allFilesExist = fileResults.every(f => f.exists);
  const allContentPassed = contentResults.every(c => c.checks.every(ch => ch.pass));
  
  if (allFilesExist && allContentPassed) return 'PASS';
  if (allFilesExist) return 'REVIEW';
  return 'FAIL';
}

function collectIssues(fileResults, contentResults) {
  const issues = [];
  
  fileResults.filter(f => !f.exists).forEach(f => {
    issues.push({ type: 'ERROR', message: `文件缺失: ${f.file}` });
  });
  
  fileResults.filter(f => f.hasTodo).forEach(f => {
    issues.push({ type: 'WARNING', message: `包含 TODO: ${f.file}` });
  });
  
  contentResults.forEach(c => {
    c.checks.filter(ch => !ch.pass).forEach(ch => {
      issues.push({ type: 'WARNING', message: `${c.file}: 缺少 ${ch.name}` });
    });
  });
  
  return issues;
}

function generateRecommendations(fileResults, contentResults) {
  const recommendations = [];
  
  if (fileResults.some(f => f.hasTodo)) {
    recommendations.push('替换所有 TODO 占位符为实际内容');
  }
  
  contentResults.forEach(c => {
    if (c.checks.some(ch => !ch.pass)) {
      recommendations.push(`完善 ${c.file} 的结构`);
    }
  });
  
  return recommendations;
}

Step 4: 生成 README.md

const readme = `# ${config.display_name}

${config.description}

## Quick Start

### 触发词

${config.triggers.map(t => `- "${t}"`).join('\n')}

### 执行模式

**${config.execution_mode === 'sequential' ? 'Sequential (顺序)' : 'Autonomous (自主)'}**

${config.execution_mode === 'sequential' ?
  `阶段按固定顺序执行：\n${config.sequential_config.phases.map((p, i) => 
    `${i + 1}. ${p.name}`
  ).join('\n')}` :
  `动作由编排器动态选择：\n${config.autonomous_config.actions.map(a => 
    `- ${a.name}: ${a.description || ''}`
  ).join('\n')}`}

## Usage

\`\`\`
# 直接触发
用户: ${config.triggers[0]}

# 或使用 Skill 名称
用户: /skill ${config.skill_name}
\`\`\`

## Output

- **格式**: ${config.output.format}
- **位置**: \`${config.output.location}\`
- **文件名**: \`${config.output.filename_pattern}\`

## Directory Structure

\`\`\`
.claude/skills/${config.skill_name}/
├── SKILL.md                    # 入口文件
├── phases/                     # 执行阶段
${config.execution_mode === 'sequential' ?
  config.sequential_config.phases.map(p => `│   ├── ${p.id}.md`).join('\n') :
  `│   ├── orchestrator.md
│   ├── state-schema.md
│   └── actions/
${config.autonomous_config.actions.map(a => `│       ├── ${a.id}.md`).join('\n')}`}
├── specs/                      # 规范文件
│   ├── ${config.skill_name}-requirements.md
│   ├── quality-standards.md
${config.execution_mode === 'autonomous' ? '│   └── action-catalog.md' : ''}
└── templates/                  # 模板文件
    └── agent-base.md
\`\`\`

## Customization

### 修改执行逻辑

编辑 \`phases/\` 目录下的阶段文件。

### 调整质量标准

编辑 \`specs/quality-standards.md\`。

### 添加新${config.execution_mode === 'sequential' ? '阶段' : '动作'}

${config.execution_mode === 'sequential' ?
  `1. 在 \`phases/\` 创建新的阶段文件 (如 \`03.5-new-step.md\`)
2. 更新 SKILL.md 的执行流程` :
  `1. 在 \`phases/actions/\` 创建新的动作文件
2. 更新 \`specs/action-catalog.md\`
3. 在 \`phases/orchestrator.md\` 添加选择逻辑`}

## Related Documents

- [设计规范](../_shared/SKILL-DESIGN-SPEC.md)
- [执行模式规范](specs/../../../skill-generator/specs/execution-modes.md)

---

*Generated by skill-generator v1.0*
`;

Write(`${skillDir}/README.md`, readme);

Step 5: 输出最终结果

const finalResult = {
  skill_name: config.skill_name,
  skill_path: skillDir,
  execution_mode: config.execution_mode,
  
  generated_files: [
    'SKILL.md',
    'README.md',
    ...filesToCheck
  ],
  
  validation: report.summary,
  
  next_steps: [
    '1. 审阅生成的文件结构',
    '2. 替换 TODO 占位符',
    '3. 根据实际需求调整阶段逻辑',
    '4. 测试 Skill 执行流程',
    '5. 更新触发词和描述'
  ]
};

console.log('=== Skill 生成完成 ===');
console.log(`路径: ${skillDir}`);
console.log(`模式: ${config.execution_mode}`);
console.log(`状态: ${report.summary.status}`);
console.log('');
console.log('下一步:');
finalResult.next_steps.forEach(s => console.log(s));

Output

{workDir}/validation-report.json - 验证报告
{skillDir}/README.md - 使用说明

Completion

Skill 生成流程完成。用户可以：

查看生成的 Skill 目录
根据验证报告修复问题
自定义执行逻辑
测试 Skill 功能


### specs/execution-modes.md

```markdown
# Execution Modes Specification

两种 Skill 执行模式的详细规范定义。

---

## 模式概览

| 特性 | Sequential (顺序) | Autonomous (自主) |
|------|-------------------|-------------------|
| 执行顺序 | 固定（数字前缀） | 动态（编排器决策） |
| 阶段依赖 | 强依赖 | 弱依赖/无依赖 |
| 状态管理 | 隐式（阶段产出） | 显式（状态文件） |
| 适用场景 | 流水线任务 | 交互式任务 |
| 复杂度 | 低 | 中-高 |
| 可扩展性 | 插入子阶段 | 添加新动作 |

---

## Mode 1: Sequential (顺序模式)

### 定义

阶段按固定顺序线性执行，每个阶段的输出作为下一阶段的输入。

### 目录结构

phases/ ├── 01-{first-step}.md ├── 02-{second-step}.md ├── 02.5-{sub-step}.md # 可选：子阶段 ├── 03-{third-step}.md └── ...


### 执行流程

┌─────────┐ ┌─────────┐ ┌─────────┐ │Phase 01 │────▶│Phase 02 │────▶│Phase 03 │────▶ ... └─────────┘ └─────────┘ └─────────┘ │ │ │ ▼ ▼ ▼ output1.json output2.md output3.md


### Phase 文件规范

```markdown
# Phase N: {阶段名称}

{一句话描述}

## Objective

{详细目标}

## Input

- 依赖: {上一阶段产出}
- 配置: {配置文件}

## Execution Steps

### Step 1: {步骤}
{执行代码或说明}

### Step 2: {步骤}
{执行代码或说明}

## Output

- **File**: `{输出文件}`
- **Format**: {JSON/Markdown}

## Next Phase

→ [Phase N+1: xxx](0N+1-xxx.md)

适用场景

文档生成: 收集 → 分析 → 组装 → 优化
代码分析: 扫描 → 解析 → 报告
数据处理: 提取 → 转换 → 加载

优点

逻辑清晰，易于理解
调试简单，可逐阶段验证
输出可预测

缺点

灵活性低
难以处理分支逻辑
用户交互受限

Mode 2: Autonomous (自主模式)

定义

无固定执行顺序，由编排器 (Orchestrator) 根据当前状态动态选择下一个动作。

目录结构

phases/
├── orchestrator.md          # 编排器：核心决策逻辑
├── state-schema.md          # 状态结构定义
└── actions/                 # 独立动作（无顺序）
    ├── action-{a}.md
    ├── action-{b}.md
    ├── action-{c}.md
    └── ...

核心组件

1. Orchestrator (编排器)

# Orchestrator

## Role

根据当前状态选择并执行下一个动作。

## State Reading

读取状态文件: `{workDir}/state.json`

## Decision Logic

```javascript
function selectNextAction(state) {
  // 1. 检查终止条件
  if (state.status === 'completed') return null;
  if (state.error_count > MAX_RETRIES) return 'action-abort';
  
  // 2. 根据状态选择动作
  if (!state.initialized) return 'action-init';
  if (state.pending_items.length > 0) return 'action-process';
  if (state.needs_review) return 'action-review';
  
  // 3. 默认动作
  return 'action-complete';
}

Execution Loop

while (true) {
  state = readState();
  action = selectNextAction(state);
  if (!action) break;
  
  result = executeAction(action, state);
  updateState(result);
}


#### 2. State Schema (状态结构)

```markdown
# State Schema

## 状态文件

位置: `{workDir}/state.json`

## 结构定义

```typescript
interface SkillState {
  // 元信息
  skill_name: string;
  started_at: string;
  updated_at: string;
  
  // 执行状态
  status: 'pending' | 'running' | 'completed' | 'failed';
  current_action: string | null;
  completed_actions: string[];
  
  // 业务数据
  context: Record<string, any>;
  pending_items: any[];
  results: Record<string, any>;
  
  // 错误追踪
  errors: Array<{
    action: string;
    message: string;
    timestamp: string;
  }>;
  error_count: number;
}

初始状态

{
  "skill_name": "{skill-name}",
  "started_at": "{ISO8601}",
  "updated_at": "{ISO8601}",
  "status": "pending",
  "current_action": null,
  "completed_actions": [],
  "context": {},
  "pending_items": [],
  "results": {},
  "errors": [],
  "error_count": 0
}


#### 3. Action (动作)

```markdown
# Action: {action-name}

## Purpose

{动作目的}

## Preconditions

- [ ] 条件1
- [ ] 条件2

## Execution

{执行逻辑}

## State Updates

```javascript
return {
  completed_actions: [...state.completed_actions, 'action-name'],
  results: {
    ...state.results,
    action_name: { /* 结果 */ }
  },
  // 其他状态更新
};

Next Actions (Hints)

成功时: action-{next}
失败时: action-retry 或 action-abort


### 执行流程

┌─────────────────────────────────────────────────────────────────┐ │ Orchestrator Loop │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ │ Read │────▶│ Select │────▶│ Execute │ │ │ │ │ │ State │ │ Action │ │ Action │ │ │ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ ▲ │ │ │ │ │ │ ▼ │ │ │ │ │ ┌──────────┐ │ │ │ │ └───────────│ Update │◀────────────────────────┘ │ │ │ │ State │ │ │ │ └──────────┘ │ │ │ │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────┐ │ │ │ Termination? │ │ │ │ - completed │ │ │ │ - max_retries │ │ │ │ - user_abort │ │ │ └──────────────────┘ │ └─────────────────────────────────────────────────────────────────┘


### 动作目录 (Action Catalog)

在 `specs/action-catalog.md` 中定义：

```markdown
# Action Catalog

## Available Actions

| Action | Purpose | Preconditions | Effects |
|--------|---------|---------------|---------|
| action-init | 初始化状态 | status=pending | status=running |
| action-process | 处理待办项 | pending_items.length>0 | pending_items-- |
| action-review | 用户审核 | needs_review=true | needs_review=false |
| action-complete | 完成任务 | pending_items.length=0 | status=completed |
| action-abort | 中止任务 | error_count>MAX | status=failed |

## Action Dependencies Graph

```mermaid
graph TD
    INIT[action-init] --> PROCESS[action-process]
    PROCESS --> PROCESS
    PROCESS --> REVIEW[action-review]
    REVIEW --> PROCESS
    REVIEW --> COMPLETE[action-complete]
    PROCESS --> ABORT[action-abort]


### 适用场景

- **交互式任务**: 问答、对话、表单填写
- **状态机任务**: Issue 管理、工作流审批
- **探索式任务**: 调试、诊断、搜索

### 优点

- 高度灵活，适应动态需求
- 支持复杂分支逻辑
- 易于扩展新动作

### 缺点

- 复杂度高
- 状态管理开销
- 调试难度大

---

## 模式选择指南

### 决策流程

用户需求分析 │ ▼ ┌────────────────────────────┐ │ 阶段间是否有强依赖关系？ │ └────────────────────────────┘ │ ├── 是 → Sequential │ └── 否 → 继续判断 │ ▼ ┌────────────────────────────┐ │ 是否需要动态响应用户意图？ │ └────────────────────────────┘ │ ├── 是 → Autonomous │ └── 否 → Sequential


### 快速判断表

| 问题 | Sequential | Autonomous |
|------|------------|------------|
| 输出结构是否固定？ | ✓ | ✗ |
| 是否需要用户多轮交互？ | ✗ | ✓ |
| 阶段是否可以跳过/重复？ | ✗ | ✓ |
| 是否有复杂分支逻辑？ | ✗ | ✓ |
| 调试是否需要简单？ | ✓ | ✗ |

---

## 混合模式

某些复杂 Skill 可能需要混合使用两种模式：

phases/ ├── 01-init.md # Sequential: 初始化 ├── 02-orchestrator.md # Autonomous: 核心交互循环 │ └── actions/ │ ├── action-a.md │ └── action-b.md └── 03-finalize.md # Sequential: 收尾


**适用场景**:
- 初始化和收尾固定，中间交互灵活
- 多阶段任务，某阶段需要动态决策

specs/skill-requirements.md

# Skill Requirements Specification

新 Skill 创建的需求收集规范。

---

## 必需信息

### 1. 基本信息

| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `skill_name` | string | ✓ | Skill 标识符（小写-连字符） |
| `display_name` | string | ✓ | 显示名称 |
| `description` | string | ✓ | 一句话描述 |
| `triggers` | string[] | ✓ | 触发关键词列表 |

### 2. 执行模式

| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `execution_mode` | enum | ✓ | `sequential` \| `autonomous` \| `hybrid` |
| `phase_count` | number | 条件 | Sequential 模式下的阶段数 |
| `action_count` | number | 条件 | Autonomous 模式下的动作数 |

### 2.5 上下文策略 (P0 增强)

| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `context_strategy` | enum | ✓ | `file` \| `memory` |

**策略对比**:

| 策略 | 持久化 | 可调试 | 可恢复 | 适用场景 |
|------|--------|--------|--------|----------|
| `file` | ✓ | ✓ | ✓ | 复杂多阶段任务（推荐） |
| `memory` | ✗ | ✗ | ✗ | 简单线性任务 |

### 2.6 LLM 集成配置 (P1 增强)

| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `llm_integration` | object | 可选 | LLM 调用配置 |
| `llm_integration.enabled` | boolean | - | 是否启用 LLM 调用 |
| `llm_integration.default_tool` | enum | - | `gemini` \| `qwen` \| `codex` |
| `llm_integration.fallback_chain` | string[] | - | 失败时的备选工具链 |

### 3. 工具依赖

| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `allowed_tools` | string[] | ✓ | 允许使用的工具列表 |
| `mcp_tools` | string[] | 可选 | 需要的 MCP 工具 |

### 4. 输出配置

| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `output_format` | enum | ✓ | `markdown` \| `html` \| `json` |
| `output_location` | string | ✓ | 输出目录模式 |

---

## 配置文件结构

```typescript
interface SkillConfig {
  // 基本信息
  skill_name: string;           // "my-skill"
  display_name: string;         // "My Skill"
  description: string;          // "一句话描述"
  triggers: string[];           // ["keyword1", "keyword2"]
  
  // 执行模式
  execution_mode: 'sequential' | 'autonomous' | 'hybrid';

  // 上下文策略 (P0 增强)
  context_strategy: 'file' | 'memory';  // 默认: 'file'

  // LLM 集成配置 (P1 增强)
  llm_integration?: {
    enabled: boolean;                    // 是否启用 LLM 调用
    default_tool: 'gemini' | 'qwen' | 'codex';
    fallback_chain: string[];            // ['gemini', 'qwen', 'codex']
    mode: 'analysis' | 'write';          // 默认 mode
  };

  // Sequential 模式配置
  sequential_config?: {
    phases: Array<{
      id: string;               // "01-init"
      name: string;             // "Initialization"
      description: string;      // "收集初始配置"
      input: string[];          // 输入依赖
      output: string;           // 输出文件
    }>;
  };
  
  // Autonomous 模式配置
  autonomous_config?: {
    state_schema: {
      fields: Array<{
        name: string;
        type: string;
        description: string;
      }>;
    };
    actions: Array<{
      id: string;               // "action-init"
      name: string;             // "Initialize"
      description: string;      // "初始化状态"
      preconditions: string[];  // 前置条件
      effects: string[];        // 执行效果
    }>;
    termination_conditions: string[];
  };
  
  // 工具依赖
  allowed_tools: string[];      // ["Task", "Read", "Write", ...]
  mcp_tools?: string[];         // ["mcp__chrome__*"]
  
  // 输出配置
  output: {
    format: 'markdown' | 'html' | 'json';
    location: string;           // ".workflow/.scratchpad/{skill}-{timestamp}"
    filename_pattern: string;   // "{name}-output.{ext}"
  };
  
  // 质量配置
  quality?: {
    dimensions: string[];       // ["completeness", "consistency", ...]
    pass_threshold: number;     // 80
  };
  
  // 元数据
  created_at: string;
  version: string;
}

需求收集问题

Phase 1: 基本信息

AskUserQuestion({
  questions: [
    {
      question: "Skill 的名称是什么？（英文，小写-连字符格式）",
      header: "Skill 名称",
      multiSelect: false,
      options: [
        { label: "自动生成", description: "根据描述自动生成名称" },
        { label: "手动输入", description: "输入自定义名称" }
      ]
    },
    {
      question: "Skill 的主要用途是什么？",
      header: "用途类型",
      multiSelect: false,
      options: [
        { label: "文档生成", description: "生成 Markdown/HTML 文档" },
        { label: "代码分析", description: "分析代码结构、质量、安全" },
        { label: "交互管理", description: "管理 Issue、任务、工作流" },
        { label: "数据处理", description: "ETL、转换、报告生成" },
        { label: "自定义", description: "其他用途" }
      ]
    }
  ]
});

Phase 2: 执行模式

AskUserQuestion({
  questions: [
    {
      question: "选择执行模式：",
      header: "执行模式",
      multiSelect: false,
      options: [
        { 
          label: "Sequential (顺序)", 
          description: "阶段按固定顺序执行，适合流水线任务（推荐）" 
        },
        { 
          label: "Autonomous (自主)", 
          description: "动态选择执行路径，适合交互式任务" 
        },
        { 
          label: "Hybrid (混合)", 
          description: "初始化和收尾固定，中间交互灵活" 
        }
      ]
    }
  ]
});

Phase 3: 阶段/动作定义

Sequential 模式

AskUserQuestion({
  questions: [
    {
      question: "需要多少个执行阶段？",
      header: "阶段数量",
      multiSelect: false,
      options: [
        { label: "3 阶段", description: "简单: 收集 → 处理 → 输出" },
        { label: "5 阶段", description: "标准: 收集 → 探索 → 分析 → 组装 → 验证" },
        { label: "7 阶段", description: "完整: 包含并行处理和迭代优化" },
        { label: "自定义", description: "手动指定阶段" }
      ]
    }
  ]
});

Autonomous 模式

AskUserQuestion({
  questions: [
    {
      question: "核心动作有哪些？",
      header: "动作定义",
      multiSelect: true,
      options: [
        { label: "初始化 (init)", description: "设置初始状态" },
        { label: "列表 (list)", description: "显示当前项目" },
        { label: "创建 (create)", description: "创建新项目" },
        { label: "编辑 (edit)", description: "修改现有项目" },
        { label: "删除 (delete)", description: "删除项目" },
        { label: "完成 (complete)", description: "完成任务" }
      ]
    }
  ]
});

Phase 4: 上下文策略 (P0 增强)

AskUserQuestion({
  questions: [
    {
      question: "选择上下文管理策略：",
      header: "上下文策略",
      multiSelect: false,
      options: [
        {
          label: "文件策略 (file)",
          description: "持久化到 .scratchpad，支持调试和恢复（推荐）"
        },
        {
          label: "内存策略 (memory)",
          description: "仅在运行时保持，速度快但无法恢复"
        }
      ]
    }
  ]
});

Phase 5: LLM 集成 (P1 增强)

AskUserQuestion({
  questions: [
    {
      question: "是否需要 LLM 调用能力？",
      header: "LLM 集成",
      multiSelect: false,
      options: [
        {
          label: "启用 LLM 调用",
          description: "使用 gemini/qwen/codex 进行分析或生成"
        },
        {
          label: "不需要",
          description: "仅使用本地工具"
        }
      ]
    }
  ]
});

// 如果启用 LLM
if (llmEnabled) {
  AskUserQuestion({
    questions: [
      {
        question: "选择默认 LLM 工具：",
        header: "LLM 工具",
        multiSelect: false,
        options: [
          { label: "Gemini", description: "大上下文，适合分析任务（推荐）" },
          { label: "Qwen", description: "代码生成能力强" },
          { label: "Codex", description: "自主执行能力强，适合实现任务" }
        ]
      }
    ]
  });
}

Phase 6: 工具依赖

AskUserQuestion({
  questions: [
    {
      question: "需要哪些工具？",
      header: "工具选择",
      multiSelect: true,
      options: [
        { label: "基础工具", description: "Task, Read, Write, Glob, Grep, Bash" },
        { label: "用户交互", description: "AskUserQuestion" },
        { label: "Chrome 截图", description: "mcp__chrome__*" },
        { label: "外部搜索", description: "mcp__exa__search" },
        { label: "CCW CLI 调用", description: "ccw cli (gemini/qwen/codex)" }
      ]
    }
  ]
});

验证规则

名称验证

function validateSkillName(name) {
  const rules = [
    { test: /^[a-z][a-z0-9-]*$/, msg: "必须以小写字母开头，只包含小写字母、数字、连字符" },
    { test: /^.{3,30}$/, msg: "长度 3-30 字符" },
    { test: /^(?!.*--)/, msg: "不能有连续连字符" },
    { test: /[^-]$/, msg: "不能以连字符结尾" }
  ];
  
  for (const rule of rules) {
    if (!rule.test.test(name)) {
      return { valid: false, error: rule.msg };
    }
  }
  return { valid: true };
}

配置验证

function validateSkillConfig(config) {
  const errors = [];
  
  // 必需字段
  if (!config.skill_name) errors.push("缺少 skill_name");
  if (!config.description) errors.push("缺少 description");
  if (!config.execution_mode) errors.push("缺少 execution_mode");
  
  // 模式特定验证
  if (config.execution_mode === 'sequential') {
    if (!config.sequential_config?.phases?.length) {
      errors.push("Sequential 模式需要定义 phases");
    }
  } else if (config.execution_mode === 'autonomous') {
    if (!config.autonomous_config?.actions?.length) {
      errors.push("Autonomous 模式需要定义 actions");
    }
  }
  
  return { valid: errors.length === 0, errors };
}

示例配置

Sequential 模式示例 (增强版)

{
  "skill_name": "api-docs-generator",
  "display_name": "API Docs Generator",
  "description": "Generate API documentation from source code",
  "triggers": ["generate api docs", "api documentation"],
  "execution_mode": "sequential",
  "context_strategy": "file",
  "llm_integration": {
    "enabled": true,
    "default_tool": "gemini",
    "fallback_chain": ["gemini", "qwen"],
    "mode": "analysis"
  },
  "sequential_config": {
    "phases": [
      {
        "id": "01-scan",
        "name": "Code Scanning",
        "output": "endpoints.json",
        "agent": { "type": "universal-executor", "run_in_background": false }
      },
      {
        "id": "02-analyze",
        "name": "LLM Analysis",
        "output": "analysis.json",
        "agent": { "type": "llm", "tool": "gemini", "mode": "analysis" }
      },
      {
        "id": "03-generate",
        "name": "Doc Generation",
        "output": "api-docs.md",
        "agent": { "type": "universal-executor", "run_in_background": false }
      }
    ]
  },
  "allowed_tools": ["Task", "Read", "Write", "Glob", "Grep", "Bash"],
  "output": {
    "format": "markdown",
    "location": ".workflow/.scratchpad/api-docs-{timestamp}",
    "filename_pattern": "{name}-api-docs.md"
  }
}

Autonomous 模式示例

{
  "skill_name": "task-manager",
  "display_name": "Task Manager",
  "description": "Interactive task management with CRUD operations",
  "triggers": ["manage tasks", "task list", "create task"],
  "execution_mode": "autonomous",
  "autonomous_config": {
    "state_schema": {
      "fields": [
        { "name": "tasks", "type": "Task[]", "description": "任务列表" },
        { "name": "current_view", "type": "string", "description": "当前视图" }
      ]
    },
    "actions": [
      { "id": "action-list", "name": "List Tasks", "preconditions": [], "effects": ["显示任务列表"] },
      { "id": "action-create", "name": "Create Task", "preconditions": [], "effects": ["添加新任务"] },
      { "id": "action-edit", "name": "Edit Task", "preconditions": ["task_selected"], "effects": ["更新任务"] },
      { "id": "action-delete", "name": "Delete Task", "preconditions": ["task_selected"], "effects": ["删除任务"] }
    ],
    "termination_conditions": ["user_exit", "error_limit"]
  },
  "allowed_tools": ["Task", "AskUserQuestion", "Read", "Write"],
  "output": {
    "format": "json",
    "location": ".workflow/.scratchpad/tasks",
    "filename_pattern": "tasks.json"
  }
}


### templates/skill-md.md

```markdown
# SKILL.md Template

用于生成新 Skill 入口文件的模板。

## ⚠️ 重要：YAML Front Matter 规范

> **CRITICAL**: SKILL.md 文件必须以 YAML front matter 开头，即以 `---` 作为文件第一行。
>
> **禁止**使用以下格式：
> - `# Title` 然后 `## Metadata` + yaml 代码块 ❌
> - 任何在 `---` 之前的内容 ❌
>
> **正确格式**：文件第一行必须是 `---`

## 可直接应用的模板

以下是完整的 SKILL.md 模板。生成时**直接复制应用**，将 `{{变量}}` 替换为实际值：

---
name: {{skill_name}}
description: {{description}}. Triggers on {{triggers}}.
allowed-tools: {{allowed_tools}}
---

# {{display_name}}

{{description}}

## Architecture Overview

\`\`\`
{{architecture_diagram}}
\`\`\`

## Key Design Principles

{{design_principles}}

## Execution Flow

{{execution_flow}}

## Directory Setup

\`\`\`javascript
const timestamp = new Date().toISOString().slice(0,19).replace(/[-:T]/g, '');
const workDir = \`{{output_location}}\`;

Bash(\`mkdir -p "\${workDir}"\`);
{{additional_dirs}}
\`\`\`

## Output Structure

\`\`\`
{{output_structure}}
\`\`\`

## Reference Documents

{{reference_table}}

---

## 变量说明

| 变量 | 类型 | 来源 |
|------|------|------|
| `{{skill_name}}` | string | config.skill_name |
| `{{display_name}}` | string | config.display_name |
| `{{description}}` | string | config.description |
| `{{triggers}}` | string | config.triggers.join(", ") |
| `{{allowed_tools}}` | string | config.allowed_tools.join(", ") |
| `{{architecture_diagram}}` | string | 根据 execution_mode 生成 |
| `{{design_principles}}` | string | 根据 execution_mode 生成 |
| `{{execution_flow}}` | string | 根据 phases/actions 生成 |
| `{{output_location}}` | string | config.output.location |
| `{{additional_dirs}}` | string | 根据 execution_mode 生成 |
| `{{output_structure}}` | string | 根据配置生成 |
| `{{reference_table}}` | string | 根据文件列表生成 |

## 生成函数

```javascript
function generateSkillMd(config) {
  const template = Read('templates/skill-md.md');
  
  return template
    .replace(/\{\{skill_name\}\}/g, config.skill_name)
    .replace(/\{\{display_name\}\}/g, config.display_name)
    .replace(/\{\{description\}\}/g, config.description)
    .replace(/\{\{triggers\}\}/g, config.triggers.map(t => `"${t}"`).join(", "))
    .replace(/\{\{allowed_tools\}\}/g, config.allowed_tools.join(", "))
    .replace(/\{\{architecture_diagram\}\}/g, generateArchitecture(config))
    .replace(/\{\{design_principles\}\}/g, generatePrinciples(config))
    .replace(/\{\{execution_flow\}\}/g, generateFlow(config))
    .replace(/\{\{output_location\}\}/g, config.output.location)
    .replace(/\{\{additional_dirs\}\}/g, generateAdditionalDirs(config))
    .replace(/\{\{output_structure\}\}/g, generateOutputStructure(config))
    .replace(/\{\{reference_table\}\}/g, generateReferenceTable(config));
}

Sequential 模式示例

---
name: api-docs-generator
description: Generate API documentation from source code. Triggers on "generate api docs", "api documentation".
allowed-tools: Task, Read, Write, Glob, Grep, Bash
---

# API Docs Generator

Generate API documentation from source code.

## Architecture Overview

\`\`\`
┌─────────────────────────────────────────────────────────────────┐
│  Phase 1: Scanning        → endpoints.json                      │
│           ↓                                                      │
│  Phase 2: Parsing         → schemas.json                        │
│           ↓                                                      │
│  Phase 3: Generation      → api-docs.md                         │
└─────────────────────────────────────────────────────────────────┘
\`\`\`

Autonomous 模式示例

---
name: task-manager
description: Interactive task management with CRUD operations. Triggers on "manage tasks", "task list".
allowed-tools: Task, AskUserQuestion, Read, Write
---

# Task Manager

Interactive task management with CRUD operations.

## Architecture Overview

\`\`\`
┌─────────────────────────────────────────────────────────────────┐
│           Orchestrator (状态驱动决策)                             │
└───────────────┬─────────────────────────────────────────────────┘
                │
    ┌───────────┼───────────┬───────────┐
    ↓           ↓           ↓           ↓
┌───────┐  ┌───────┐  ┌───────┐  ┌───────┐
│ List  │  │Create │  │ Edit  │  │Delete │
└───────┘  └───────┘  └───────┘  └───────┘
\`\`\`


### templates/sequential-phase.md

```markdown
# Sequential Phase Template

顺序模式 Phase 文件的模板。

## 模板结构

```markdown
# Phase {{phase_number}}: {{phase_name}}

{{phase_description}}

## Objective

{{objectives}}

## Input

- 依赖: `{{input_dependency}}`
- 配置: `{workDir}/skill-config.json`

## Execution Steps

### Step 1: {{step_1_name}}

\`\`\`javascript
{{step_1_code}}
\`\`\`

### Step 2: {{step_2_name}}

\`\`\`javascript
{{step_2_code}}
\`\`\`

### Step 3: {{step_3_name}}

\`\`\`javascript
{{step_3_code}}
\`\`\`

## Output

- **File**: `{{output_file}}`
- **Format**: {{output_format}}

## Quality Checklist

{{quality_checklist}}

## Next Phase

{{next_phase_link}}

变量说明

变量	说明
`{{phase_number}}`	阶段序号 (1, 2, 3...)
`{{phase_name}}`	阶段名称
`{{phase_description}}`	一句话描述
`{{objectives}}`	目标列表
`{{input_dependency}}`	输入依赖文件
`{{step_N_name}}`	步骤名称
`{{step_N_code}}`	步骤代码
`{{output_file}}`	输出文件名
`{{output_format}}`	输出格式
`{{quality_checklist}}`	质量检查项
`{{next_phase_link}}`	下一阶段链接

Phase 类型模板

1. 收集型 Phase (Collection)

# Phase 1: Requirements Collection

收集用户需求和项目配置。

## Objective

- 收集用户输入
- 自动检测项目信息
- 生成配置文件

## Execution Steps

### Step 1: 用户交互

\`\`\`javascript
const userInput = await AskUserQuestion({
  questions: [
    {
      question: "请选择...",
      header: "选项",
      multiSelect: false,
      options: [
        { label: "选项A", description: "..." },
        { label: "选项B", description: "..." }
      ]
    }
  ]
});
\`\`\`

### Step 2: 自动检测

\`\`\`javascript
// 检测项目信息
const packageJson = JSON.parse(Read('package.json'));
const projectName = packageJson.name;
\`\`\`

### Step 3: 生成配置

\`\`\`javascript
const config = {
  name: projectName,
  userChoice: userInput["选项"],
  // ...
};

Write(`${workDir}/config.json`, JSON.stringify(config, null, 2));
\`\`\`

## Output

- **File**: `config.json`
- **Format**: JSON

2. 分析型 Phase (Analysis)

# Phase 2: Deep Analysis

深度分析代码结构。

## Objective

- 扫描代码文件
- 提取关键信息
- 生成分析报告

## Execution Steps

### Step 1: 文件扫描

\`\`\`javascript
const files = Glob('src/**/*.ts');
\`\`\`

### Step 2: 内容分析

\`\`\`javascript
const analysisResults = [];
for (const file of files) {
  const content = Read(file);
  // 分析逻辑
  analysisResults.push({ file, /* 分析结果 */ });
}
\`\`\`

### Step 3: 生成报告

\`\`\`javascript
Write(`${workDir}/analysis.json`, JSON.stringify(analysisResults, null, 2));
\`\`\`

## Output

- **File**: `analysis.json`
- **Format**: JSON

3. 并行型 Phase (Parallel)

# Phase 3: Parallel Processing

并行处理多个子任务。

## Objective

- 启动多个 Agent 并行执行
- 收集各 Agent 结果
- 合并输出

## Execution Steps

### Step 1: 准备任务

\`\`\`javascript
const tasks = [
  { id: 'task-a', prompt: '...' },
  { id: 'task-b', prompt: '...' },
  { id: 'task-c', prompt: '...' }
];
\`\`\`

### Step 2: 并行执行

\`\`\`javascript
const results = await Promise.all(
  tasks.map(task => 
    Task({
      subagent_type: 'universal-executor',
      run_in_background: false,
      prompt: task.prompt
    })
  )
);
\`\`\`

### Step 3: 合并结果

\`\`\`javascript
const merged = results.map((r, i) => ({
  task_id: tasks[i].id,
  result: JSON.parse(r)
}));

Write(`${workDir}/parallel-results.json`, JSON.stringify(merged, null, 2));
\`\`\`

## Output

- **File**: `parallel-results.json`
- **Format**: JSON

4. 组装型 Phase (Assembly)

# Phase 4: Document Assembly

组装最终输出文档。

## Objective

- 读取各阶段产出
- 合并内容
- 生成最终文档

## Execution Steps

### Step 1: 读取产出

\`\`\`javascript
const config = JSON.parse(Read(`${workDir}/config.json`));
const analysis = JSON.parse(Read(`${workDir}/analysis.json`));
const sections = Glob(`${workDir}/sections/*.md`).map(f => Read(f));
\`\`\`

### Step 2: 组装内容

\`\`\`javascript
const document = \`
# \${config.name}

## 概述
\${config.description}

## 详细内容
\${sections.join('\\n\\n')}
\`;
\`\`\`

### Step 3: 写入文件

\`\`\`javascript
Write(`${workDir}/${config.name}-output.md`, document);
\`\`\`

## Output

- **File**: `{name}-output.md`
- **Format**: Markdown

5. 验证型 Phase (Validation)

# Phase 5: Validation

验证输出质量。

## Objective

- 检查输出完整性
- 验证内容质量
- 生成验证报告

## Execution Steps

### Step 1: 完整性检查

\`\`\`javascript
const outputFile = `${workDir}/${config.name}-output.md`;
const content = Read(outputFile);
const completeness = {
  hasTitle: content.includes('# '),
  hasSections: content.match(/## /g)?.length >= 3,
  hasContent: content.length > 500
};
\`\`\`

### Step 2: 质量评估

\`\`\`javascript
const quality = {
  completeness: Object.values(completeness).filter(v => v).length / 3 * 100,
  // 其他维度...
};
\`\`\`

### Step 3: 生成报告

\`\`\`javascript
const report = {
  status: quality.completeness >= 80 ? 'PASS' : 'REVIEW',
  scores: quality,
  issues: []
};

Write(`${workDir}/validation-report.json`, JSON.stringify(report, null, 2));
\`\`\`

## Output

- **File**: `validation-report.json`
- **Format**: JSON

生成函数

function generateSequentialPhase(phaseConfig, index, phases, skillConfig) {
  const prevPhase = index > 0 ? phases[index - 1] : null;
  const nextPhase = index < phases.length - 1 ? phases[index + 1] : null;
  
  return `# Phase ${index + 1}: ${phaseConfig.name}

${phaseConfig.description || `执行 ${phaseConfig.name}`}

## Objective

- ${phaseConfig.objectives?.join('\n- ') || 'TODO: 定义目标'}

## Input

- 依赖: \`${prevPhase ? prevPhase.output : 'user input'}\`
- 配置: \`{workDir}/skill-config.json\`

## Execution Steps

### Step 1: 准备

\`\`\`javascript
${prevPhase ? 
  `const prevOutput = JSON.parse(Read(\`\${workDir}/${prevPhase.output}\`));` :
  '// 首阶段，从配置开始'}
\`\`\`

### Step 2: 处理

\`\`\`javascript
// TODO: 实现核心逻辑
\`\`\`

### Step 3: 输出

\`\`\`javascript
Write(\`\${workDir}/${phaseConfig.output}\`, JSON.stringify(result, null, 2));
\`\`\`

## Output

- **File**: \`${phaseConfig.output}\`
- **Format**: ${phaseConfig.output.endsWith('.json') ? 'JSON' : 'Markdown'}

## Quality Checklist

- [ ] 输入验证通过
- [ ] 核心逻辑执行成功
- [ ] 输出格式正确

${nextPhase ? 
  `## Next Phase\n\n→ [Phase ${index + 2}: ${nextPhase.name}](${nextPhase.id}.md)` :
  '## Completion\n\n此为最后阶段。'}
`;
}


### templates/autonomous-orchestrator.md

```markdown
# Autonomous Orchestrator Template

自主模式编排器的模板。

## 模板结构

```markdown
# Orchestrator

## Role

根据当前状态选择并执行下一个动作。

## State Management

### 读取状态

\`\`\`javascript
const state = JSON.parse(Read(`${workDir}/state.json`));
\`\`\`

### 更新状态

\`\`\`javascript
function updateState(updates) {
  const state = JSON.parse(Read(`${workDir}/state.json`));
  const newState = {
    ...state,
    ...updates,
    updated_at: new Date().toISOString()
  };
  Write(`${workDir}/state.json`, JSON.stringify(newState, null, 2));
  return newState;
}
\`\`\`

## Decision Logic

\`\`\`javascript
function selectNextAction(state) {
  // 1. 终止条件检查
  {{termination_checks}}
  
  // 2. 错误限制检查
  if (state.error_count >= 3) {
    return 'action-abort';
  }
  
  // 3. 动作选择逻辑
  {{action_selection_logic}}
  
  // 4. 默认完成
  return 'action-complete';
}
\`\`\`

## Execution Loop

\`\`\`javascript
async function runOrchestrator() {
  console.log('=== Orchestrator Started ===');
  
  let iteration = 0;
  const MAX_ITERATIONS = 100;
  
  while (iteration < MAX_ITERATIONS) {
    iteration++;
    
    // 1. 读取当前状态
    const state = JSON.parse(Read(`${workDir}/state.json`));
    console.log(`[Iteration ${iteration}] Status: ${state.status}`);
    
    // 2. 选择下一个动作
    const actionId = selectNextAction(state);
    
    if (!actionId) {
      console.log('No action selected, terminating.');
      break;
    }
    
    console.log(`[Iteration ${iteration}] Executing: ${actionId}`);
    
    // 3. 更新状态：当前动作
    updateState({ current_action: actionId });
    
    // 4. 执行动作
    try {
      const actionPrompt = Read(`phases/actions/${actionId}.md`);
      
      const result = await Task({
        subagent_type: 'universal-executor',
        run_in_background: false,
        prompt: \`
[STATE]
\${JSON.stringify(state, null, 2)}

[ACTION]
\${actionPrompt}

[RETURN]
Return JSON with stateUpdates field.
\`
      });
      
      const actionResult = JSON.parse(result);
      
      // 5. 更新状态：动作完成
      updateState({
        current_action: null,
        completed_actions: [...state.completed_actions, actionId],
        ...actionResult.stateUpdates
      });
      
    } catch (error) {
      // 错误处理
      updateState({
        current_action: null,
        errors: [...state.errors, {
          action: actionId,
          message: error.message,
          timestamp: new Date().toISOString()
        }],
        error_count: state.error_count + 1
      });
    }
  }
  
  console.log('=== Orchestrator Finished ===');
}
\`\`\`

## Action Catalog

| Action | Purpose | Preconditions |
|--------|---------|---------------|
{{action_catalog_table}}

## Termination Conditions

{{termination_conditions_list}}

## Error Recovery

| Error Type | Recovery Strategy |
|------------|-------------------|
| 动作执行失败 | 重试最多 3 次 |
| 状态不一致 | 回滚到上一个稳定状态 |
| 用户中止 | 保存当前状态，允许恢复 |

变量说明

变量	说明
`{{termination_checks}}`	终止条件检查代码
`{{action_selection_logic}}`	动作选择逻辑代码
`{{action_catalog_table}}`	动作目录表格
`{{termination_conditions_list}}`	终止条件列表

生成函数

function generateOrchestrator(config) {
  const actions = config.autonomous_config.actions;
  const terminations = config.autonomous_config.termination_conditions || [];
  
  // 生成终止条件检查
  const terminationChecks = terminations.map(t => {
    const checks = {
      'user_exit': 'if (state.status === "user_exit") return null;',
      'error_limit': 'if (state.error_count >= 3) return "action-abort";',
      'task_completed': 'if (state.status === "completed") return null;',
      'max_iterations': 'if (state.iteration_count >= 100) return "action-abort";'
    };
    return checks[t] || `if (state.${t}) return null;`;
  }).join('\n  ');
  
  // 生成动作选择逻辑
  const actionSelectionLogic = actions.map(action => {
    if (!action.preconditions?.length) {
      return `// ${action.name}: 无前置条件，需要手动添加选择逻辑`;
    }
    const conditions = action.preconditions.map(p => `state.${p}`).join(' && ');
    return `if (${conditions}) return '${action.id}';`;
  }).join('\n  ');
  
  // 生成动作目录表格
  const actionCatalogTable = actions.map(a => 
    `| [${a.id}](actions/${a.id}.md) | ${a.description || a.name} | ${a.preconditions?.join(', ') || '-'} |`
  ).join('\n');
  
  // 生成终止条件列表
  const terminationConditionsList = terminations.map(t => `- ${t}`).join('\n');
  
  return template
    .replace('{{termination_checks}}', terminationChecks)
    .replace('{{action_selection_logic}}', actionSelectionLogic)
    .replace('{{action_catalog_table}}', actionCatalogTable)
    .replace('{{termination_conditions_list}}', terminationConditionsList);
}

编排策略

1. 优先级策略

按预定义优先级选择动作：

const PRIORITY = ['action-init', 'action-process', 'action-review', 'action-complete'];

function selectByPriority(state, availableActions) {
  for (const actionId of PRIORITY) {
    if (availableActions.includes(actionId) && checkPreconditions(actionId, state)) {
      return actionId;
    }
  }
  return null;
}

2. 用户驱动策略

询问用户选择下一个动作：

async function selectByUser(state, availableActions) {
  const response = await AskUserQuestion({
    questions: [{
      question: "选择下一个操作：",
      header: "操作",
      multiSelect: false,
      options: availableActions.map(a => ({
        label: a.name,
        description: a.description
      }))
    }]
  });
  
  return availableActions.find(a => a.name === response["操作"])?.id;
}

3. 状态驱动策略

完全基于状态自动决策：

function selectByState(state) {
  // 初始化
  if (state.status === 'pending') return 'action-init';
  
  // 有待处理项
  if (state.pending_items?.length > 0) return 'action-process';
  
  // 需要审核
  if (state.needs_review) return 'action-review';
  
  // 完成
  return 'action-complete';
}

状态机示例

stateDiagram-v2
    [*] --> pending
    pending --> running: action-init
    running --> running: action-process
    running --> running: action-review
    running --> completed: action-complete
    running --> failed: action-abort
    completed --> [*]
    failed --> [*]


### templates/autonomous-action.md

```markdown
# Autonomous Action Template

自主模式动作文件的模板。

## 模板结构

```markdown
# Action: {{action_name}}

{{action_description}}

## Purpose

{{purpose}}

## Preconditions

{{preconditions_list}}

## Execution

\`\`\`javascript
async function execute(state) {
  {{execution_code}}
}
\`\`\`

## State Updates

\`\`\`javascript
return {
  stateUpdates: {
    {{state_updates}}
  }
};
\`\`\`

## Error Handling

| Error Type | Recovery |
|------------|----------|
{{error_handling_table}}

## Next Actions (Hints)

{{next_actions_hints}}

变量说明

变量	说明
`{{action_name}}`	动作名称
`{{action_description}}`	动作描述
`{{purpose}}`	详细目的
`{{preconditions_list}}`	前置条件列表
`{{execution_code}}`	执行代码
`{{state_updates}}`	状态更新
`{{error_handling_table}}`	错误处理表格
`{{next_actions_hints}}`	后续动作提示

动作类型模板

1. 初始化动作 (Init)

# Action: Initialize

初始化 Skill 执行状态。

## Purpose

设置初始状态，准备执行环境。

## Preconditions

- [ ] state.status === 'pending'

## Execution

\`\`\`javascript
async function execute(state) {
  // 1. 创建工作目录
  Bash(\`mkdir -p "\${workDir}"\`);
  
  // 2. 初始化数据
  const initialData = {
    items: [],
    metadata: {}
  };
  
  // 3. 返回状态更新
  return {
    stateUpdates: {
      status: 'running',
      context: initialData
    }
  };
}
\`\`\`

## State Updates

\`\`\`javascript
return {
  stateUpdates: {
    status: 'running',
    started_at: new Date().toISOString(),
    context: { /* 初始数据 */ }
  }
};
\`\`\`

## Next Actions

- 成功: 进入主处理循环
- 失败: action-abort

2. 列表动作 (List)

# Action: List Items

显示当前项目列表。

## Purpose

展示所有项目供用户查看和选择。

## Preconditions

- [ ] state.status === 'running'

## Execution

\`\`\`javascript
async function execute(state) {
  const items = state.context.items || [];
  
  if (items.length === 0) {
    console.log('暂无项目');
  } else {
    console.log('项目列表:');
    items.forEach((item, i) => {
      console.log(\`\${i + 1}. \${item.name} - \${item.status}\`);
    });
  }
  
  return {
    stateUpdates: {
      last_action: 'list',
      current_view: 'list'
    }
  };
}
\`\`\`

## State Updates

\`\`\`javascript
return {
  stateUpdates: {
    current_view: 'list',
    last_viewed_at: new Date().toISOString()
  }
};
\`\`\`

## Next Actions

- 用户选择创建: action-create
- 用户选择编辑: action-edit
- 用户退出: action-complete

3. 创建动作 (Create)

# Action: Create Item

创建新项目。

## Purpose

引导用户创建新项目。

## Preconditions

- [ ] state.status === 'running'

## Execution

\`\`\`javascript
async function execute(state) {
  // 1. 收集信息
  const input = await AskUserQuestion({
    questions: [{
      question: "请输入项目名称：",
      header: "名称",
      multiSelect: false,
      options: [
        { label: "手动输入", description: "输入自定义名称" }
      ]
    }]
  });
  
  // 2. 创建项目
  const newItem = {
    id: Date.now().toString(),
    name: input["名称"],
    status: 'pending',
    created_at: new Date().toISOString()
  };
  
  // 3. 返回状态更新
  return {
    stateUpdates: {
      context: {
        ...state.context,
        items: [...(state.context.items || []), newItem]
      },
      last_created_id: newItem.id
    }
  };
}
\`\`\`

## State Updates

\`\`\`javascript
return {
  stateUpdates: {
    'context.items': [...items, newItem],
    last_action: 'create',
    last_created_id: newItem.id
  }
};
\`\`\`

## Next Actions

- 继续创建: action-create
- 返回列表: action-list

4. 编辑动作 (Edit)

# Action: Edit Item

编辑现有项目。

## Purpose

修改已存在的项目。

## Preconditions

- [ ] state.status === 'running'
- [ ] state.selected_item_id !== null

## Execution

\`\`\`javascript
async function execute(state) {
  const itemId = state.selected_item_id;
  const items = state.context.items || [];
  const item = items.find(i => i.id === itemId);
  
  if (!item) {
    throw new Error(\`Item not found: \${itemId}\`);
  }
  
  // 1. 显示当前值
  console.log(\`当前名称: \${item.name}\`);
  
  // 2. 收集新值
  const input = await AskUserQuestion({
    questions: [{
      question: "请输入新名称（留空保持不变）：",
      header: "新名称",
      multiSelect: false,
      options: [
        { label: "保持不变", description: \`当前: \${item.name}\` },
        { label: "手动输入", description: "输入新名称" }
      ]
    }]
  });
  
  // 3. 更新项目
  const updatedItems = items.map(i => 
    i.id === itemId 
      ? { ...i, name: input["新名称"] || i.name, updated_at: new Date().toISOString() }
      : i
  );
  
  return {
    stateUpdates: {
      context: { ...state.context, items: updatedItems },
      selected_item_id: null
    }
  };
}
\`\`\`

## State Updates

\`\`\`javascript
return {
  stateUpdates: {
    'context.items': updatedItems,
    selected_item_id: null,
    last_action: 'edit'
  }
};
\`\`\`

## Next Actions

- 返回列表: action-list

5. 删除动作 (Delete)

# Action: Delete Item

删除项目。

## Purpose

从列表中移除项目。

## Preconditions

- [ ] state.status === 'running'
- [ ] state.selected_item_id !== null

## Execution

\`\`\`javascript
async function execute(state) {
  const itemId = state.selected_item_id;
  const items = state.context.items || [];
  
  // 1. 确认删除
  const confirm = await AskUserQuestion({
    questions: [{
      question: "确认删除此项目？",
      header: "确认",
      multiSelect: false,
      options: [
        { label: "确认删除", description: "不可恢复" },
        { label: "取消", description: "返回列表" }
      ]
    }]
  });
  
  if (confirm["确认"] === "取消") {
    return { stateUpdates: { selected_item_id: null } };
  }
  
  // 2. 执行删除
  const updatedItems = items.filter(i => i.id !== itemId);
  
  return {
    stateUpdates: {
      context: { ...state.context, items: updatedItems },
      selected_item_id: null
    }
  };
}
\`\`\`

## State Updates

\`\`\`javascript
return {
  stateUpdates: {
    'context.items': filteredItems,
    selected_item_id: null,
    last_action: 'delete'
  }
};
\`\`\`

## Next Actions

- 返回列表: action-list

6. 完成动作 (Complete)

# Action: Complete

完成任务并退出。

## Purpose

保存最终状态，结束 Skill 执行。

## Preconditions

- [ ] state.status === 'running'

## Execution

\`\`\`javascript
async function execute(state) {
  // 1. 保存最终数据
  Write(\`\${workDir}/final-output.json\`, JSON.stringify(state.context, null, 2));
  
  // 2. 生成摘要
  const summary = {
    total_items: state.context.items?.length || 0,
    duration: Date.now() - new Date(state.started_at).getTime(),
    actions_executed: state.completed_actions.length
  };
  
  console.log('任务完成！');
  console.log(\`处理项目: \${summary.total_items}\`);
  console.log(\`执行动作: \${summary.actions_executed}\`);
  
  return {
    stateUpdates: {
      status: 'completed',
      summary: summary
    }
  };
}
\`\`\`

## State Updates

\`\`\`javascript
return {
  stateUpdates: {
    status: 'completed',
    completed_at: new Date().toISOString(),
    summary: { /* 统计信息 */ }
  }
};
\`\`\`

## Next Actions

- 无（终止状态）

生成函数

function generateAction(actionConfig, skillConfig) {
  return `# Action: ${actionConfig.name}

${actionConfig.description || `执行 ${actionConfig.name} 操作`}

## Purpose

${actionConfig.purpose || 'TODO: 描述此动作的详细目的'}

## Preconditions

${actionConfig.preconditions?.map(p => `- [ ] ${p}`).join('\n') || '- [ ] 无特殊前置条件'}

## Execution

\`\`\`javascript
async function execute(state) {
  // TODO: 实现动作逻辑
  
  return {
    stateUpdates: {
      completed_actions: [...state.completed_actions, '${actionConfig.id}']
    }
  };
}
\`\`\`

## State Updates

\`\`\`javascript
return {
  stateUpdates: {
    // TODO: 定义状态更新
${actionConfig.effects?.map(e => `    // Effect: ${e}`).join('\n') || ''}
  }
};
\`\`\`

## Error Handling

| Error Type | Recovery |
|------------|----------|
| 数据验证失败 | 返回错误，不更新状态 |
| 执行异常 | 记录错误，增加 error_count |

## Next Actions (Hints)

- 成功: 由编排器根据状态决定
- 失败: 重试或 action-abort
`;
}


### ../_shared/SKILL-DESIGN-SPEC.md

```markdown
# Skill 设计规范 v1.0

> 基于 `software-manual` 和 `copyright-docs` 两个成熟 Skill 的设计模式提炼

---

## 目录

1. [设计理念](#1-设计理念)
2. [目录结构规范](#2-目录结构规范)
3. [核心组件定义](#3-核心组件定义)
4. [SKILL.md 入口规范](#4-skillmd-入口规范)
5. [Phase 阶段设计规范](#5-phase-阶段设计规范)
6. [Specs 规范文件设计](#6-specs-规范文件设计)
7. [Templates 模板设计](#7-templates-模板设计)
8. [Scripts 脚本规范](#8-scripts-脚本规范)
9. [Prompt 工程规范](#9-prompt-工程规范)
10. [质量控制规范](#10-质量控制规范)
11. [最佳实践清单](#11-最佳实践清单)
12. [示例模板](#12-示例模板)

---

## 1. 设计理念

### 1.1 核心原则

| 原则 | 说明 | 实践 |
|------|------|------|
| **阶段化执行** | 复杂任务分解为有序阶段 | 使用 `phases/` 目录，数字前缀控制顺序 |
| **关注点分离** | 逻辑、配置、视图分离 | `phases/`(逻辑) + `specs/`(配置) + `templates/`(视图) |
| **简要返回** | Agent 返回路径+摘要，避免上下文溢出 | 返回 JSON 简要信息，文件存储完整内容 |
| **配置驱动** | 规范作为"配置文件"，易于调整行为 | 修改 `specs/` 无需触及 `phases/` |
| **模板复用** | 提取通用片段，确保一致性 | `templates/` 存放可复用内容 |

### 1.2 架构模式

┌─────────────────────────────────────────────────────────────────┐ │ Context-Optimized Architecture │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ SKILL.md (入口) → 描述目标、定义阶段、链接资源 │ │ ↓ │ │ Phase 1: 收集 → 用户输入 + 自动检测 → config.json │ │ ↓ │ │ Phase 2: 分析 → 并行 Agent → sections/*.md │ │ ↓ │ │ Phase N: 汇总 → 交叉检查 → summary.md │ │ ↓ │ │ Phase N+1: 组装 → 合并文件 → 最终产物 │ │ ↓ │ │ Phase N+2: 迭代 → 用户反馈 → 优化 │ │ │ └─────────────────────────────────────────────────────────────────┘


---

## 2. 目录结构规范

### 2.1 标准目录结构

[skill-name]/ ├── SKILL.md # 【必需】技能入口：元数据 + 架构 + 执行流程 ├── phases/ # 【必需】执行阶段 Prompt │ ├── 01-{first-step}.md # 数字前缀定义顺序 │ ├── 02-{second-step}.md │ ├── 02.5-{sub-step}.md # 小数点用于插入子步骤 │ └── ... ├── specs/ # 【必需】规范与约束 │ ├── {domain}-requirements.md # 领域特定要求 │ ├── quality-standards.md # 质量标准 │ └── writing-style.md # 写作风格（如适用） ├── templates/ # 【推荐】可复用模板 │ ├── agent-base.md # Agent 基础 Prompt 模板 │ ├── output-shell.{ext} # 输出外壳模板（html/md） │ └── css/ # 样式文件（如适用） ├── scripts/ # 【可选】辅助脚本 │ ├── {tool}.py # Python 脚本 │ └── {tool}-runner.md # 脚本使用说明 └── outputs/ # 【运行时】执行产物（不纳入版本控制）


### 2.2 命名约定

| 类型 | 规则 | 示例 |
|------|------|------|
| Skill 目录 | 小写-连字符 | `software-manual`, `copyright-docs` |
| Phase 文件 | `NN-{动作}.md` | `01-metadata-collection.md` |
| Spec 文件 | `{领域}-{类型}.md` | `cpcc-requirements.md` |
| Template 文件 | `{用途}-{类型}.{ext}` | `agent-base.md`, `tiddlywiki-shell.html` |
| 输出文件 | `section-{N}-{名称}.md` | `section-2-architecture.md` |

---

## 3. 核心组件定义

### 3.1 组件职责矩阵

| 组件 | 职责 | 内容类型 | 修改频率 |
|------|------|----------|----------|
| `SKILL.md` | 入口 + 编排 | 元数据、架构图、执行流程 | 低（结构稳定） |
| `phases/*.md` | 执行逻辑 | 步骤说明、Prompt、代码示例 | 中（优化迭代） |
| `specs/*.md` | 约束配置 | 规则、标准、检查清单 | 中（需求变更） |
| `templates/*` | 可复用片段 | Prompt 模板、输出格式 | 低（通用稳定） |
| `scripts/*` | 自动化 | Python/JS 脚本 | 高（功能增强） |

### 3.2 组件依赖关系

```mermaid
graph TD
    SKILL[SKILL.md] --> P1[phases/01-*]
    P1 --> P2[phases/02-*]
    P2 --> PN[phases/N-*]
    
    P1 -.->|引用| SPEC[specs/*]
    P2 -.->|引用| SPEC
    PN -.->|引用| SPEC
    
    P1 -.->|使用| TPL[templates/*]
    PN -.->|使用| TPL
    
    P2 -->|调用| SCR[scripts/*]
    
    style SKILL fill:#e1f5fe
    style SPEC fill:#fff3e0
    style TPL fill:#e8f5e9
    style SCR fill:#fce4ec

4. SKILL.md 入口规范

4.1 必需结构

---
name: {skill-name}
description: {一句话描述}. {触发关键词}. Triggers on "{关键词1}", "{关键词2}".
allowed-tools: Task, AskUserQuestion, Read, Bash, Glob, Grep, Write, {其他MCP工具}
---

# {Skill 标题}

{一段话描述 Skill 的用途和产出}

## Architecture Overview

{ASCII 或 Mermaid 架构图}

## Key Design Principles

1. **原则1**: 说明
2. **原则2**: 说明
...

## Execution Flow

{阶段执行流程图}

## Agent Configuration (如适用)

| Agent | Role | Output File | Focus Areas |
|-------|------|-------------|-------------|
| ... | ... | ... | ... |

## Directory Setup

{工作目录创建代码}

## Output Structure

{输出目录结构}

## Reference Documents

| Document | Purpose |
|----------|---------|
| [phases/01-xxx.md](phases/01-xxx.md) | ... |
| ... | ... |

4.2 Front Matter 规范

---
name: skill-name              # 必需：Skill 唯一标识
description: |                # 必需：描述 + 触发词
  Generate XXX documents. 
  Triggers on "keyword1", "keyword2".
allowed-tools: |              # 必需：允许使用的工具
  Task, AskUserQuestion, Read, Bash, 
  Glob, Grep, Write, mcp__chrome__*
---

5. Phase 阶段设计规范

5.1 Phase 文件结构

# Phase N: {阶段名称}

{一句话描述此阶段目标}

## Objective

{详细目标说明}
- 目标1
- 目标2

## Execution Steps

### Step 1: {步骤名称}

{代码或说明}

### Step 2: {步骤名称}

{代码或说明}

## Output

- **File**: `{输出文件名}`
- **Location**: `{输出路径}`
- **Format**: {JSON/Markdown/HTML}

## Next Phase

Proceed to [Phase N+1: xxx](0N+1-xxx.md) with the generated {产出}.

5.2 Phase 类型

类型	特点	示例
收集型	用户交互 + 自动检测	`01-requirements-discovery.md`
探索型	代码分析 + 结构识别	`02-project-exploration.md`
并行型	多 Agent 并行执行	`03-parallel-analysis.md`
汇总型	交叉检查 + 质量验证	`03.5-consolidation.md`
组装型	合并产出 + 格式化	`04-document-assembly.md`
迭代型	用户反馈 + 优化	`05-iterative-refinement.md`

5.3 Phase 编号规则

01-xxx.md      # 主阶段
02-xxx.md      # 主阶段
02.5-xxx.md    # 子阶段（插入 02 和 03 之间）
03-xxx.md      # 主阶段

6. Specs 规范文件设计

6.1 Specs 类型

类型	用途	示例
领域要求	领域特定合规性	`cpcc-requirements.md`
质量标准	输出质量评估	`quality-standards.md`
写作风格	内容风格指南	`writing-style.md`
模板规范	输出格式定义	`html-template.md`

6.2 Specs 结构模板

# {规范名称}

{规范用途说明}

## When to Use

| Phase | Usage | Section |
|-------|-------|---------|
| Phase N | {使用场景} | {引用章节} |
| ... | ... | ... |

---

## Requirements

### Category 1

- [ ] 检查项1
- [ ] 检查项2

### Category 2

| 项目 | 要求 | 检查方式 |
|------|------|----------|
| ... | ... | ... |

## Validation Function

{验证函数代码}

## Error Handling

| Error | Recovery |
|-------|----------|
| ... | ... |

6.3 质量标准示例结构

# Quality Standards

## Quality Dimensions

### 1. Completeness (25%)
{评分标准}

### 2. Consistency (25%)
{评分标准}

### 3. Depth (25%)
{评分标准}

### 4. Readability (25%)
{评分标准}

## Quality Gates

| Gate | Threshold | Action |
|------|-----------|--------|
| Pass | ≥ 80% | 继续执行 |
| Review | 60-79% | 处理警告后继续 |
| Fail | < 60% | 必须修复 |

## Issue Classification

### Errors (Must Fix)
- ...

### Warnings (Should Fix)
- ...

### Info (Nice to Have)
- ...

7. Templates 模板设计

7.1 Agent 基础模板

# Agent Base Template

## 通用提示词结构

[ROLE] 你是{角色}，专注于{职责}。

[TASK]
{任务描述}
- 输出: {output_path}
- 格式: {format}
- 范围: {scope}

[CONSTRAINTS]
- 约束1
- 约束2

[OUTPUT_FORMAT]
1. 直接写入文件
2. 返回 JSON 简要信息

[QUALITY_CHECKLIST]
- [ ] 检查项1
- [ ] 检查项2

## 变量说明

| 变量 | 来源 | 示例 |
|------|------|------|
| {output_dir} | Phase 1 | .workflow/.scratchpad/xxx |
| ... | ... | ... |

## Agent 配置映射

{AGENT_ROLES, AGENT_SECTIONS, AGENT_FILES, AGENT_FOCUS}

7.2 输出模板规范

<!-- output-shell.html 示例 -->
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>{{title}}</title>
    <style>
        /* 内嵌 CSS */
        {{styles}}
    </style>
</head>
<body>
    <div id="app">
        {{content}}
    </div>
    <script>
        /* 内嵌 JS */
        {{scripts}}
    </script>
</body>
</html>

7.3 占位符规范

占位符格式	用途	示例
`{{variable}}`	简单变量替换	`{{title}}`
`${variable}`	JavaScript 模板字符串	`${workDir}`
`{placeholder}`	Prompt 占位	`{intro}`, `{diagram}`

8. Scripts 脚本规范

8.1 脚本类型

类型	用途	命名
提取器	从代码提取信息	`extract_*.py`
组装器	合并/转换文件	`assemble_*.py`
验证器	检查合规性	`validate_*.py`
辅助器	工具函数	`*_helper.py`

8.2 脚本使用说明文件

每个脚本应有对应的 .md 说明文件：

# {Script Name} Runner

## Purpose

{脚本用途}

## Usage

{命令行使用方式}

## Parameters

| 参数 | 说明 | 默认值 |
|------|------|--------|
| ... | ... | ... |

## Output

{输出说明}

## Example

{使用示例}

9. Prompt 工程规范

9.1 Prompt 结构标准

[ROLE] {角色定义}

[PROJECT CONTEXT]
项目类型: {type}
语言: {language}
名称: {name}

[TASK]
{任务描述}
输出: {output_path}

[INPUT]
- 配置: {config_path}
- 扫描路径: {scan_paths}

[CONTENT REQUIREMENTS]
- 标题层级: # ## ### (最多3级)
- 代码块: ```language ... ``` (必须标注语言)
- 表格: | col1 | col2 | 格式
- 列表: 有序 1. 2. 3. / 无序 - - -

[FOCUS]
{重点关注项}

[OUTPUT FORMAT]
{输出格式说明}

[RETURN JSON]
{返回结构}

9.2 效率优化原则

原则	Before (冗余)	After (精简)
角色简化	"你是一个专业的系统架构师，具有丰富的软件设计经验..."	`[ROLE] 系统架构师，专注于分层设计和模块依赖`
模板驱动	"请按照以下格式输出: 首先写一个二级标题..."	`[TEMPLATE] ## 2. 标题 {content}`
焦点明确	"分析项目的各个方面，包括架构、模块、依赖等"	`[FOCUS] 1. 分层 2. 模块 3. 依赖 4. 数据流`
返回简洁	"请返回详细的分析结果，包括所有发现的问题..."	`[RETURN] {"status":"completed","output_file":"xxx.md","summary":"<50字"}`

9.3 Agent 返回格式标准

interface AgentReturn {
  status: "completed" | "partial" | "failed";
  output_file: string;           // 输出文件路径
  summary: string;               // 最多 50 字摘要
  cross_module_notes?: string[]; // 跨模块备注
  stats?: {                      // 统计信息
    diagrams?: number;
    words?: number;
  };
  screenshots_needed?: Array<{   // 截图需求（如适用）
    id: string;
    url: string;
    description: string;
  }>;
}

10. 质量控制规范

10.1 质量维度

维度	权重	检查项
完整性	25%	所有必需章节存在且有实质内容
一致性	25%	术语、格式、风格统一
深度	25%	内容详尽、示例充分
可读性	25%	结构清晰、语言简洁

10.2 质量门控

const QUALITY_GATES = {
  pass: { threshold: 80, action: "继续执行" },
  review: { threshold: 60, action: "处理警告后继续" },
  fail: { threshold: 0, action: "必须修复后重试" }
};

10.3 问题分类

级别	前缀	含义	处理方式
Error	E	阻塞性问题	必须修复
Warning	W	影响质量	建议修复
Info	I	可改进项	可选修复

10.4 自动化检查函数模板

function runQualityChecks(workDir) {
  const results = {
    completeness: checkCompleteness(workDir),
    consistency: checkConsistency(workDir),
    depth: checkDepth(workDir),
    readability: checkReadability(workDir)
  };

  results.overall = Object.values(results).reduce((a, b) => a + b) / 4;
  
  return {
    score: results.overall,
    gate: results.overall >= 80 ? 'pass' : 
          results.overall >= 60 ? 'review' : 'fail',
    details: results
  };
}

11. 最佳实践清单

11.1 Skill 设计

单一职责: 每个 Skill 专注一个领域
清晰入口: SKILL.md 完整描述目标和流程
阶段分解: 复杂任务拆分为 3-7 个阶段
顺序命名: 使用数字前缀控制执行顺序

11.2 Phase 设计

明确目标: 每个 Phase 有清晰的输入输出
独立可测: 每个 Phase 可单独调试
链接下一步: 明确说明后续阶段

11.3 Prompt 设计

角色明确: 使用 [ROLE] 定义 Agent 身份
任务具体: 使用 [TASK] 明确执行目标
约束清晰: 使用 [CONSTRAINTS] 定义边界
返回简洁: Agent 返回路径+摘要，非完整内容

11.4 质量控制

规范驱动: 使用 specs/ 定义可验证的标准
汇总检查: 设置 Consolidation 阶段交叉验证
问题分级: 区分 Error/Warning/Info
迭代优化: 支持用户反馈循环

12. 示例模板

12.1 新 Skill 快速启动模板

# 创建 Skill 目录结构
mkdir -p my-skill/{phases,specs,templates,scripts}

# 创建核心文件
touch my-skill/SKILL.md
touch my-skill/phases/{01-collection,02-analysis,03-assembly}.md
touch my-skill/specs/{requirements,quality-standards}.md
touch my-skill/templates/agent-base.md

12.2 SKILL.md 最小模板

---
name: my-skill
description: Generate XXX. Triggers on "keyword1", "keyword2".
allowed-tools: Task, AskUserQuestion, Read, Bash, Glob, Grep, Write
---

# My Skill

Generate XXX through multi-phase analysis.

## Execution Flow

1. Phase 1: Collection → config.json
2. Phase 2: Analysis → sections/*.md
3. Phase 3: Assembly → output.md

## Reference Documents

| Document | Purpose |
|----------|---------|
| [phases/01-collection.md](phases/01-collection.md) | 信息收集 |
| [phases/02-analysis.md](phases/02-analysis.md) | 代码分析 |
| [phases/03-assembly.md](phases/03-assembly.md) | 文档组装 |

附录 A: 设计对比

设计点	software-manual	copyright-docs
阶段数	6	5
并行 Agent	6	6
输出格式	HTML	Markdown
质量检查	4 维度评分	CPCC 合规检查
截图支持	Chrome MCP	无
迭代优化	用户反馈循环	合规验证循环

附录 B: 工具依赖

工具	用途	适用 Skill
`Task`	启动子 Agent	所有
`AskUserQuestion`	用户交互	所有
`Read/Write/Glob/Grep`	文件操作	所有
`Bash`	脚本执行	需要自动化
`mcp__chrome__*`	浏览器截图	UI 相关

规范版本: 1.0
基于: software-manual, copyright-docs
最后更新: 2026-01-03

Source: https://github.com/catlog22/Claude-Code-Workflow#.claude~skills~skill-generator

Content curated from original sources, copyright belongs to authors

Grade A

8.3AI Score

Best Practices

Checking...

Try this Skill

User Rating

USER RATING

0UP

0DOWN

Loading files...

WORKS WITH

Claude

Codex

Gemini

OpenCode

OpenClaw

Copilot

Cursor

Windsurf

Cline

Roo

Kiro

Junie

Augment

Warp

Goose