Claude-Code-Workflow/.claude/skills_lib/team-skill-designer-v2/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
team-skill-designer	Design and generate unified team skills with role-based routing. All team members invoke ONE skill, SKILL.md routes to role-specific execution via --role arg. Triggers on "design team skill", "create team skill", "team skill designer".	Task, AskUserQuestion, Read, Write, Bash, Glob, Grep

Team Skill Designer v2

Meta-skill for creating unified team skills where all team members invoke ONE skill with role-based routing. Generates a complete skill package with SKILL.md as role router and roles/ folder for per-role execution detail.

v2 Style: 生成的技能包遵循 v3 撰写规范 — text + decision tables + flow symbols, 无伪代码, <placeholder> 占位符, 显式节拍控制。

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│  Team Skill Designer (this meta-skill)                          │
│  → Collect requirements → Analyze patterns → Generate skill pkg │
└───────────────┬─────────────────────────────────────────────────┘
                │
    ┌───────────┼───────────┬───────────┬───────────┐
    ↓           ↓           ↓           ↓           ↓
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Phase 1 │ │ Phase 2 │ │ Phase 3 │ │ Phase 4 │ │ Phase 5 │
│ Require │ │ Pattern │ │  Skill  │ │  Integ  │ │  Valid  │
│ Collect │ │ Analyze │ │  Gen    │ │  Verify │ │         │
└─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘
     ↓           ↓           ↓           ↓           ↓
  team-        pattern-    preview/    integ-     validated
  config.json  analysis   SKILL.md +  report     skill pkg
               .json      roles/*.md  .json      → delivery

Key Innovation: Unified Skill + Role Router

Before (command approach): 5 separate command files → 5 separate skill paths

After (unified skill approach):

.claude/skills/team-<name>/
├── SKILL.md          →  Skill(skill="team-<name>", args="--role=xxx")
├── roles/
│   ├── coordinator/
│   │   ├── role.md
│   │   └── commands/
│   ├── <worker-1>/
│   │   ├── role.md
│   │   └── commands/
│   └── <worker-N>/
│       ├── role.md
│       └── commands/
└── specs/
    └── team-config.json

→ 1 skill entry point, --role arg routes to per-role execution

Core Design Patterns

Pattern 1: Role Router (Unified Entry Point)

SKILL.md parses $ARGUMENTS to extract --role:

Input: Skill(skill="team-<name>", args="--role=planner")
  → Parse --role=planner
  → Read roles/planner/role.md
  → Execute planner-specific phases

No --role → Orchestration Mode (auto route to coordinator).

Pattern 2: SKILL.md = Orchestration-Level Only

SKILL.md 仅包含编排级内容:

包含	不包含
Role Router (parse → dispatch)	Message bus 代码
Architecture 图	Task lifecycle 代码
Role Registry 表 (含 markdown links)	工具声明/使用示例
Pipeline 定义 + Cadence Control	角色特定检测逻辑
Coordinator Spawn Template	实现级代码块
Shared Infrastructure (Phase 1/5 模板)
Compact Protection

Pattern 3: Role Files = Self-Contained Execution

每个 roles/<role>/role.md 包含角色执行所需的一切:

• Identity, Boundaries (MUST/MUST NOT)
• Toolbox 表 (command links)
• Phase 2-4 核心逻辑 (text + decision tables, 无伪代码)
• Error Handling 表

关键原则: subagent 加载 role.md 后无需回读 SKILL.md 即可执行。

Pattern 4: v3 Style Output

生成的技能包遵循以下风格规则:

规则	说明
无伪代码	流程用 text + decision tables + flow symbols (→ ├─ └─)
代码块仅限工具调用	只有 Task(), TaskCreate(), Bash(), Read() 等实际执行的调用
<placeholder> 占位符	不使用 ${variable} 或 {{handlebars}}
Decision tables	所有分支逻辑用 | Condition | Action | 表格
Phase 1/5 共享	SKILL.md 定义 Shared Infrastructure, role.md 只写 Phase 2-4
Cadence Control	SKILL.md 包含节拍图和检查点定义
Compact Protection	Phase Reference 表含 Compact 列, 关键 phase 标记重读

Pattern 5: Batch Role Generation

Phase 1 一次性收集所有角色 (非逐个):

• Team name + all role definitions in one pass
• Coordinator always generated
• Worker roles collected as batch

Pattern 6: Coordinator Commands Alignment

dispatch.md 约束: owner 值匹配 Role Registry | 任务 ID 匹配 Pipeline 图 | 无幽灵角色名

monitor.md 约束: spawn prompt 含完整 Skill(skill="...", args="--role=...") | Task() 含 description + team_name + name | Message Routing 角色名匹配 Registry

验证时机: Phase 4 自动检查。

---

Mandatory Prerequisites

Do NOT skip: Read these before any execution.

Specification Documents

Document	Purpose	When
specs/team-design-patterns.md	Infrastructure patterns (9) + collaboration index	Phase 0 必读
specs/collaboration-patterns.md	11 collaboration patterns with convergence control	Phase 0 必读
specs/quality-standards.md	Quality criteria (4 dimensions + command standards)	Phase 3 前必读

Template Files

Document	Purpose
templates/skill-router-template.md	生成 SKILL.md 模板 (v3 style)
templates/role-template.md	生成 role.md 模板 (v3 style)
templates/role-command-template.md	生成 command 文件模板 (v3 style)

---

Cadence Control

节拍模型: 串行 5-Phase, 每个 Phase 产出一个 artifact 作为下一 Phase 的输入。

Phase Cadence (设计生成节拍)
═══════════════════════════════════════════════════════════════════
Phase   0          1           2            3             4          5
        │          │           │            │             │          │
     读规格  →  收集需求  →  模式分析  →  技能生成  →  集成验证  →  质量交付
        │          │           │            │             │          │
     [memory]   config     analysis     preview/       report    delivery
                .json       .json       SKILL.md       .json    → skills/
                                        roles/
                                        commands/
═══════════════════════════════════════════════════════════════════

Phase 产物链:
  Phase 0 → [in-memory] specs + templates 内化
  Phase 1 → team-config.json (角色定义 + pipeline)
  Phase 2 → pattern-analysis.json (模式映射 + 协作模式)
  Phase 3 → preview/ 完整技能包
  Phase 4 → integration-report.json (一致性报告)
  Phase 5 → validation-report.json + delivery → .claude/skills/team-<name>/

检查点:
  Phase 3 完成 → ⏸ 向用户展示 preview 结构，确认后进入 Phase 4
  Phase 5 评分 → ⏸ 评分 < 60% 则回退 Phase 3 重新生成

Phase 间衔接:

当前 Phase	完成条件	产物	下一步
Phase 0	3 个 spec + 3 个 template 已读取	in-memory	→ Phase 1
Phase 1	team-config.json 写入成功	team-config.json	→ Phase 2
Phase 2	pattern-analysis.json 写入成功	pattern-analysis.json	→ Phase 3
Phase 3	preview/ 目录下所有文件生成	preview/*	→ ⏸ 用户确认 → Phase 4
Phase 4	integration-report.json 无 FAIL 项	integration-report.json	→ Phase 5
Phase 5	score ≥ 80%	delivery to skills/	→ 完成

回退机制:

条件	回退到	动作
Phase 4 发现 FAIL	Phase 3	修复后重新生成
Phase 5 score < 60%	Phase 3	重大返工
Phase 5 score 60-79%	Phase 4	修复建议后重验

---

Execution Flow

Phase Reference Documents

Phase	Document	Purpose	Compact
0	(inline)	Read specs + templates	N/A
1	phases/01-requirements-collection.md	Batch collect team + all role definitions	完成后可压缩
2	phases/02-pattern-analysis.md	Per-role pattern matching and phase mapping	完成后可压缩
3	phases/03-skill-generation.md	Generate unified skill package	⚠️ 压缩后必须重读
4	phases/04-integration-verification.md	Verify internal consistency	压缩后必须重读
5	phases/05-validation.md	Quality gate and delivery	压缩后必须重读

⚠️ COMPACT PROTECTION: Phase 文件是执行文档。当 context compression 发生后，Phase 指令仅剩摘要时，必须立即 Read 对应 phase 文件重新加载后再继续执行。不得基于摘要执行任何 Step。

Phase 0: Specification Study (Inline)

必须在生成前读取以下文件:

1. Read specs/team-design-patterns.md → 9 基础设施模式
2. Read specs/collaboration-patterns.md → 11 协作模式
3. Read specs/quality-standards.md → 质量标准
4. Read templates/skill-router-template.md → SKILL.md 生成模板
5. Read templates/role-template.md → role.md 生成模板
6. Read templates/role-command-template.md → command 文件模板

Phase 1-5: Delegated

各 Phase 读取对应 phase 文件执行。See Phase Reference Documents table above.

---

Directory Setup

工作目录: .workflow/.scratchpad/team-skill-<timestamp>/

Bash("mkdir -p .workflow/.scratchpad/team-skill-$(date +%Y%m%d%H%M%S)")

Output Structure

.workflow/.scratchpad/team-skill-<timestamp>/
├── team-config.json             # Phase 1 output
├── pattern-analysis.json        # Phase 2 output
├── integration-report.json      # Phase 4 output
├── validation-report.json       # Phase 5 output
└── preview/                     # Phase 3 output (preview before delivery)
    ├── SKILL.md
    ├── roles/
    │   ├── coordinator/
    │   │   ├── role.md
    │   │   └── commands/
    │   └── <role-N>/
    │       ├── role.md
    │       └── commands/
    └── specs/
        └── team-config.json

Final delivery → .claude/skills/team-<name>/

Error Handling

Scenario	Resolution
Specs not found	Fall back to inline pattern knowledge
Role name conflicts	AskUserQuestion for rename
Task prefix conflicts	Suggest alternative prefix
Template variable unresolved	FAIL with specific variable name
Quality score < 60%	Re-run Phase 3 with additional context
Phase file compressed	Re-read phase file before continuing