Claude-Code-Workflow/.claude/skills/skill-generator/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
phase_count	number	条件	Sequential 模式下的阶段数
action_count	number	条件	Autonomous 模式下的动作数

3. 工具依赖

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

4. 输出配置

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

---

配置文件结构

interface SkillConfig {
  // 基本信息
  skill_name: string;           // "my-skill"
  display_name: string;         // "My Skill"
  description: string;          // "一句话描述"
  triggers: string[];           // ["keyword1", "keyword2"]
  
  // 执行模式
  execution_mode: 'sequential' | 'autonomous';
  
  // 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: 工具依赖

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" }
      ]
    }
  ]
});

---

验证规则

名称验证

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",
  "sequential_config": {
    "phases": [
      { "id": "01-scan", "name": "Code Scanning", "output": "endpoints.json" },
      { "id": "02-parse", "name": "Schema Parsing", "output": "schemas.json" },
      { "id": "03-generate", "name": "Doc Generation", "output": "api-docs.md" }
    ]
  },
  "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"
  }
}