mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
Add role and skill router templates for v3 style execution
- Introduced a comprehensive role template for generating per-role execution detail files, including purpose, style rules, and structured phases. - Added a skill router template to facilitate role-based routing in SKILL.md, detailing input parsing, role registry, orchestration mode, and shared infrastructure. - Both templates adhere to v3 conventions, emphasizing clarity and structured decision-making through markdown tables and diagrams.
This commit is contained in:
catlog22
274
.claude/skills_lib/team-skill-designer-v2/SKILL.md
Normal file
274
.claude/skills_lib/team-skill-designer-v2/SKILL.md
Normal file
@@ -0,0 +1,274 @@
|
||||
---
|
||||
name: team-skill-designer
|
||||
description: 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".
|
||||
allowed-tools: 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](specs/team-design-patterns.md) | Infrastructure patterns (9) + collaboration index | Phase 0 必读 |
|
||||
| [specs/collaboration-patterns.md](specs/collaboration-patterns.md) | 11 collaboration patterns with convergence control | Phase 0 必读 |
|
||||
| [specs/quality-standards.md](specs/quality-standards.md) | Quality criteria (4 dimensions + command standards) | Phase 3 前必读 |
|
||||
|
||||
### Template Files
|
||||
|
||||
| Document | Purpose |
|
||||
|----------|---------|
|
||||
| [templates/skill-router-template.md](templates/skill-router-template.md) | 生成 SKILL.md 模板 (v3 style) |
|
||||
| [templates/role-template.md](templates/role-template.md) | 生成 role.md 模板 (v3 style) |
|
||||
| [templates/role-command-template.md](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](phases/01-requirements-collection.md) | Batch collect team + all role definitions | 完成后可压缩 |
|
||||
| 2 | [phases/02-pattern-analysis.md](phases/02-pattern-analysis.md) | Per-role pattern matching and phase mapping | 完成后可压缩 |
|
||||
| 3 | [phases/03-skill-generation.md](phases/03-skill-generation.md) | Generate unified skill package | **⚠️ 压缩后必须重读** |
|
||||
| 4 | [phases/04-integration-verification.md](phases/04-integration-verification.md) | Verify internal consistency | 压缩后必须重读 |
|
||||
| 5 | [phases/05-validation.md](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
|
||||
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 |
|
||||
Reference in New Issue
Block a user