workflow-skill-designer

ワークフロースキルデザイナー

オーケストレーター＋フェーズのパターンに従って、構造化されたワークフロースキルを作成するメタスキルです。SKILL.md をコーディネーター、phases/ フォルダーを実行詳細として、完全なスキルパッケージを生成します。

アーキテクチャの概要

┌─────────────────────────────────────────────────────────────────┐
│  Workflow Skill Designer                                         │
│  → Analyze requirements → Design orchestrator → Generate phases  │
└───────────────┬─────────────────────────────────────────────────┘
                │
    ┌───────────┼───────────┬───────────┐
    ↓           ↓           ↓           ↓
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Phase 1 │ │ Phase 2 │ │ Phase 3 │ │ Phase 4 │
│ Require │ │  Orch   │ │ Phases  │ │ Valid   │
│ Analysis│ │ Design  │ │ Design  │ │ & Integ │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
     ↓           ↓           ↓           ↓
  workflow    SKILL.md    phases/     Complete
  config     generated   0N-*.md     skill pkg

生成される出力構造

このメタスキルが生成するスキルは、次の構造に従います。

.claude/skills/{skill-name}/
├── SKILL.md                    # Orchestrator: coordination, data flow, TodoWrite
├── phases/
│   ├── 01-{phase-name}.md      # Phase execution detail (full content)
│   ├── 02-{phase-name}.md
│   ├── ...
│   └── 0N-{phase-name}.md
├── specs/                      # [Optional] Domain specifications
└── templates/                  # [Optional] Reusable templates

コア設計パターン

成功したワークフロースキルの実装（workflow-plan、project-analyze など）から抽出したパターンです。

パターン 1：オーケストレーター＋段階的な読み込み

SKILL.md ＝ 専用のコーディネーター。以下を含みます。

• アーキテクチャ図（ASCII）
• Ref: phases/0N-xxx.md マーカーを使った実行フロー
• フェーズ参照ドキュメントの表（必要に応じて読み込み）
• フェーズ間のデータフロー
• コア規則とエラー処理

フェーズファイル ＝ 実行の詳細をすべて記載します。以下を含みます。

• エージェントのプロンプト、bash コマンド、コードの実装一式
• 検証チェックリスト、エラー処理
• 入力／出力の仕様
• 次のフェーズへのリンク

重要なルール：SKILL.md では Ref: マーカーを使ってフェーズドキュメントを参照します。フェーズドキュメントはそのフェーズの実行時にのみ読み込み、すべてを一度に読み込むことはありません。

パターン 2：TodoWrite の添付／折りたたみ

Phase starts:
  → Sub-tasks ATTACHED to TodoWrite (in_progress + pending)
  → Orchestrator executes sub-tasks sequentially

Phase ends:
  → Sub-tasks COLLAPSED back to high-level summary (completed)
  → Next phase begins

パターン 3：フェーズ間のデータフロー

Phase N output → stored in memory/variable → Phase N+1 input
                  └─ or written to session file for persistence

各フェーズは、前のフェーズの出力を次の方法で受け取ります。

• メモリ内変数（sessionId、contextPath など）
• セッションディレクトリのファイル（.workflow/active/{sessionId}/...）
• 計画メモ（蓄積された制約のドキュメント）

パターン 4：条件付きフェーズ実行

Phase N output contains condition flag
  ├─ condition met → Execute Phase N+1
  └─ condition not met → Skip to Phase N+2

パターン 5：入力の構造化

ユーザー入力（自由形式のテキスト）→ フェーズ 1 の前に構造化形式に変換：

GOAL: [objective]
SCOPE: [boundaries]
CONTEXT: [background/constraints]

パターン 6：対話形式での設定収集（SKILL.md の責務）

ワークフローの設定（自動モード、強制探索など）は、フェーズをディスパッチする前に、SKILL.md で AskUserQuestion を使って収集する必要があります。フェーズでは、これらを workflowPreferences.{key} コンテキスト変数として参照します。

アンチパターン：フェーズファイル内で $ARGUMENTS.includes(...) を使ってコマンドラインフラグ（--yes、-e、--explore）を解析します。

// CORRECT: In SKILL.md (before phase dispatch)
const prefResponse = AskUserQuestion({
  questions: [
    { question: "是否跳过确认？", header: "Auto Mode", options: [
      { label: "Interactive (Recommended)", description: "交互模式" },
      { label: "Auto", description: "跳过所有确认" }
    ]}
  ]
})
workflowPreferences = { autoYes: prefResponse.autoMode === 'Auto' }

// CORRECT: In phase files (reference only)
const autoYes = workflowPreferences.autoYes

// WRONG: In phase files (flag parsing)
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')

パターン 7：フェーズの直接引き継ぎ

あるフェーズから同じスキル内の別のフェーズを呼び出す必要がある場合、フェーズドキュメントを直接読み込んで実行します。SKILL.md を経由する Skill() ルーティングは使用しないでください。

// CORRECT: Direct handoff (executionContext already set)
Read("phases/02-lite-execute.md")
// Execute with executionContext (Mode 1)

// WRONG: Skill routing (unnecessary round-trip)
Skill(skill="workflow-lite-plan", args="--in-memory")

パターン 8：フェーズファイルの衛生管理

フェーズファイルは内部実行ドキュメントです。以下を含めてはなりません。

禁止事項	理由	正しい配置場所
フラグの解析（$ARGUMENTS.includes(...)）	設定は SKILL.md で収集する	AskUserQuestion を使って SKILL.md で収集
呼び出し構文（/skill-name "..."）	ユーザー向けドキュメントではない	削除するか、SKILL.md のみに記載
変換元の記載（Source: Converted from...）	実装詳細	削除
フェーズ間のスキルルーティング（Skill(skill="...")）	フェーズを直接読み込む	Read("phases/...") で直接読み込む

パターン 9：簡潔な復旧（フェーズの永続化）

複数フェーズにまたがるワークフローは、長い会話の中で実行されます。コンテキストの圧縮（compact）により、前のフェーズのドキュメントは自然に要約されます。この戦略では二重の保護を採用します。TodoWrite でアクティブなフェーズを追跡し、圧縮から保護するとともに、圧縮が発生した場合に sentinel をフォールバックとして使用し、復旧を開始します。

設計原則：TodoWrite の in_progress ＝アクティブなフェーズ → compact から保護 | sentinel ＝保護に失敗した場合の再読み込みフォールバック。

二重保護の仕組み：

レイヤー	役割	仕組み
1. アクティブフェーズの保護	予防	TodoWrite の in_progress マーカーで現在のフェーズを示す → compact 時にそのフェーズの内容全体を保持し、圧縮しない
2. Sentinel の再読み込み	復旧	フェーズファイルに識別子を埋め込む → 圧縮が続いた場合、sentinel のみの状態を検出した時点で直ちに再読み込み

適用する場面：直接引き継ぎ（パターン 7）によってフェーズをまたいで実行するすべての場面。特に、後続のフェーズに複雑な実行プロトコル（複数のステップ、エージェントのディスパッチ、CLI のオーケストレーション）が含まれる場合に適用します。

---

レイヤー 1：アクティブフェーズの保護（TodoWrite との連携）

TodoWrite はすでに各フェーズの実行状態を追跡しています。この情報を利用して compact の方針を制御します。

TodoWrite status → Compact behavior:
  ┌─ completed  → ✅ 可压缩（已完成，不再需要完整内容）
  ├─ in_progress → 🛡️ 禁止压缩（正在执行，必须保留完整协议）
  └─ pending    → ✅ 可压缩（尚未加载，无内容）

SKILL.md の実行フローで compact との連携を示します。

## Execution Flow

> **⚠️ COMPACT DIRECTIVE**: Context compression MUST check TodoWrite phase status.
> The phase currently marked `in_progress` is the active execution phase — preserve its FULL content.
> Only compress phases marked `completed` or `pending`.

Phase 1: Requirements Analysis    ← TodoWrite tracks status
   └─ Ref: phases/01-xxx.md
Phase 2: Execution Engine         ← TodoWrite tracks status
   └─ Ref: phases/02-xxx.md
...

TodoWrite の状態遷移に応じて、compact の保護範囲を自動的に更新します。

Phase 1: in_progress 🛡️  →  completed ✅   (compact 可压缩 Phase 1)
Phase 2: pending ✅       →  in_progress 🛡️ (compact 保护 Phase 2)

---

レイヤー 2: Sentinel 再読み込み (フォールバック復旧)

レイヤー 1 の保護があっても、compact は極端なシナリオ（超長コンテキスト、多ターンのエージェントスケジューリング）ではアクティブフェーズを圧縮してしまう可能性があります。Sentinel は復旧能力を確保します:

Phase ファイルの先頭に sentinel を埋め込む:

> **📌 COMPACT SENTINEL [Phase N: {phase-name}]**
> This phase contains {M} execution steps (Step N.1 — N.{M}).
> If you can read this sentinel but cannot find the full Step protocol below, context has been compressed.
> Recovery: `Read("phases/0N-xxx.md")`

Sentinel の設計上の特徴:

• 構造化され、目立つ → compact はこれを重要情報として要約内に保持します
• step 数を含む → 自己検証の根拠を提供します（「M 個の Step が見えるはずだが、要約しかない」）
• re-read パスを含む → テーブルを参照せずに復旧できます

---

Phase リファレンステーブル (二重の保険を統合)

| Phase | Document | Purpose | Compact |
|-------|----------|---------|---------|
| 1 | phases/01-xxx.md | Planning | TodoWrite 驱动 |
| 2 | phases/02-xxx.md | Execution | TodoWrite 驱动 + 🔄 sentinel |

**Compact Rules**:
1. **TodoWrite `in_progress`** → 保留完整内容，禁止压缩
2. **TodoWrite `completed`** → 可压缩为摘要
3. **🔄 sentinel fallback** → 带此标记的 phase 包含 compact sentinel；若 compact 后仅存 sentinel 而无完整 Step 协议，**必须立即 `Read("phases/0N-xxx.md")` 恢复后再继续**

---

チェックポイント (実行ステップ前の二重検証)

> **⚠️ CHECKPOINT**: Before proceeding, verify:
> 1. This phase is TodoWrite `in_progress` (active phase protection)
> 2. Full protocol (Step N.X — N.{M}) is in active memory, not just sentinel
> If only sentinel remains → `Read("phases/0N-xxx.md")` now.

ハンドオフコメント

// Phase N is tracked by TodoWrite — active phase protection applies.
// Sentinel fallback: if compressed despite protection, re-read triggers automatically.
Read("phases/0N-xxx.md")

実行フロー

Phase 1: Requirements Analysis
   └─ Ref: phases/01-requirements-analysis.md
      ├─ Input source: commands, descriptions, user interaction
      └─ Output: workflowConfig (phases, data flow, agents, conditions)

Phase 2: Orchestrator Design (SKILL.md)
   └─ Ref: phases/02-orchestrator-design.md
      ├─ Input: workflowConfig
      └─ Output: .claude/skills/{name}/SKILL.md

Phase 3: Phase Files Design
   └─ Ref: phases/03-phase-design.md
      ├─ Input: workflowConfig + source content
      └─ Output: .claude/skills/{name}/phases/0N-*.md

Phase 4: Validation & Integration
   └─ Ref: phases/04-validation.md
      └─ Output: Validated skill package

Phase リファレンスドキュメント (オンデマンドで読み込み):

Phase	ドキュメント	目的
1	phases/01-requirements-analysis.md	さまざまなソースからワークフロー要件を分析します
2	phases/02-orchestrator-design.md	オーケストレーションパターンを含む SKILL.md を生成します
3	phases/03-phase-design.md	完全な実行詳細を保持した phase ファイルを生成します
4	phases/04-validation.md	構造、参照、統合を検証します

入力ソース

このメタスキルは、複数のソースからのワークフロー定義を受け付けます:

ソース	説明	例
既存のコマンド	.claude/commands/ のオーケストレーター + サブコマンドを変換します	plan.md + session/start.md + tools/*.md
テキスト記述	ユーザーが自然言語でワークフローを記述します	「3 フェーズのコードレビューワークフローを作成する」
要件ドキュメント	構造化された要件ファイル	phases/agents/outputs を含む requirements.md
既存のスキル	既存のスキルをリファクタリング/再設計します	フラットなスキルをフェーズに再構成します

Frontmatter 変換ルール

コマンド形式からスキル形式へ変換する場合:

コマンドフィールド	スキルフィールド	変換
name	name	グループをプレフィックスとして付加: plan → workflow-plan
description	description	トリガーフレーズを追加: Triggers on "xxx"
argument-hint	(削除)	引数は入力処理セクションで扱います
examples	(削除)	例はインラインドキュメントに移動します
allowed-tools	allowed-tools	ワイルドカードを展開: Skill(*) → Skill、よく必要となるツールを追加します
group	(削除)	name プレフィックスに埋め込みます

オーケストレーターのコンテンツマッピング

SKILL.md に入れるものと、phase ファイルに入れるもの:

SKILL.md (コーディネーター)

セクション	コンテンツ	ソース
Frontmatter	name、description、allowed-tools	コマンドの frontmatter（変換済み）
アーキテクチャ概要	phase フローの ASCII 図	実行構造から導出
主要な設計原則	調整ルール	コマンドのコーディネーターの役割から抽出
実行フロー	Ref: マーカー付きの phase シーケンス + Phase リファレンステーブル	コマンドの実行プロセス
コアルール	オーケストレーションの制約	コマンドのコアルール
入力処理	構造化フォーマットへの変換	コマンドの入力処理
データフロー	phase 間のデータ受け渡し	コマンドのデータフロー
TodoWrite パターン	アタッチ/コラプスのライフサイクル	コマンドの TodoWrite セクション
phase 後の更新	phase 間の計画メモ / 状態更新	コマンドの phase 間更新コード
エラーハンドリング	障害からの復旧	コマンドのエラーハンドリング
コーディネーターチェックリスト	phase 前後のアクション	コマンドのコーディネーターチェックリスト
関連コマンド	前提条件とフォローアップ	コマンドの関連コマンド

フェーズファイル (実行の詳細)

内容	ルール
エージェントプロンプト全文	ソースコマンドからそのまま保持
Bash コマンドブロック	そのまま保持
コード実装	そのまま保持
検証チェックリスト	そのまま保持
エラーハンドリングの詳細	そのまま保持
入出力仕様	ソースにない場合は追加
フェーズヘッダー	# Phase N: {Name} を追加
目的セクション	箇条書きで ## Objective を追加
次フェーズリンク	次へのリンクを含む ## Next Phase を追加

重要なルール: フェーズファイルはソースに対して内容に忠実でなければなりません。要約、省略、簡略化をしてはいけません。フェーズファイルは実行指示そのものです。すべての bash コマンド、すべてのエージェントプロンプト、すべての検証ステップを保持する必要があります。

SKILL.md テンプレート

---
name: {skill-name}
description: {description}. Triggers on "{trigger1}", "{trigger2}".
allowed-tools: {tools}
---

# {Title}

{One-paragraph description of what this skill does and what it produces.}

## Architecture Overview

{ASCII diagram showing phases and data flow}

## Key Design Principles

1. **{Principle}**: {Description}
...

## Interactive Preference Collection

Collect workflow preferences via AskUserQuestion before dispatching to phases:
{AskUserQuestion code with preference derivation → workflowPreferences}

## Auto Mode Defaults

When `workflowPreferences.autoYes === true`: {auto-mode behavior}.

## Execution Flow

{Phase sequence with Ref: markers}

**Phase Reference Documents** (read on-demand when phase executes):

| Phase | Document | Purpose | Compact |
|-------|----------|---------|---------|
| 1 | [phases/01-xxx.md](phases/01-xxx.md) | ... | TodoWrite 驱动 |
| N | [phases/0N-xxx.md](phases/0N-xxx.md) | ... | TodoWrite 驱动 + 🔄 sentinel |
...

**Compact Rules**:
1. **TodoWrite `in_progress`** → 保留完整内容，禁止压缩
2. **TodoWrite `completed`** → 可压缩为摘要
3. **🔄 sentinel fallback** → 带此标记的 phase 包含 compact sentinel；若 compact 后仅存 sentinel 而无完整 Step 协议，必须立即 `Read()` 恢复

## Core Rules

1. {Rule}
...

## Input Processing

{How user input is converted to structured format}

## Data Flow

{Inter-phase data passing diagram}

## TodoWrite Pattern

{Attachment/collapse lifecycle description with examples}

## Post-Phase Updates

{State updates between phases}

## Error Handling

{Failure recovery rules}

## Coordinator Checklist

{Pre/post phase action list}

## Related Commands

{Prerequisites and follow-ups}

フェーズファイルテンプレート

# Phase N: {Phase Name}

> **📌 COMPACT SENTINEL [Phase N: {phase-name}]**
> This phase contains {M} execution steps (Step N.1 — N.{M}).
> If you can read this sentinel but cannot find the full Step protocol below, context has been compressed.
> Recovery: `Read("phases/0N-xxx.md")`
> _(Include for phases marked 🔄 in SKILL.md Phase Reference table — see Pattern 9)_

{One-sentence description of this phase's goal.}

## Objective

- {Goal 1}
- {Goal 2}

## Execution

### Step N.1: {Step Name}

{Full execution detail: commands, agent prompts, code}

### Step N.2: {Step Name}

> **⚠️ CHECKPOINT**: Before proceeding, verify:
> 1. This phase is TodoWrite `in_progress` (active phase protection)
> 2. Full protocol (Step N.X — N.{M}) is in active memory, not just sentinel
> If only sentinel remains → `Read("phases/0N-xxx.md")` now.
> _(Add checkpoints before critical execution steps: agent dispatch, CLI launch, review — see Pattern 9)_

{Full execution detail}

## Output

- **Variable**: `{variableName}` (e.g., `sessionId`)
- **File**: `{output file path}`
- **TodoWrite**: Mark Phase N completed, Phase N+1 in_progress

## Next Phase

Return to orchestrator, then auto-continue to [Phase N+1: xxx](0N+1-xxx.md).

設計判断フレームワーク

新しいワークフロースキルを設計する際は、次の問いに答えてください。

問い	影響	例
フェーズはいくつか?	ディレクトリ構造	通常 3〜7 フェーズ
どのフェーズが条件付きか?	オーケストレーターのロジック	「conflict_risk が medium 以上の場合のみ Phase 3」
フェーズ間でどのようなデータが流れるか?	Data Flow セクション	sessionId、contextPath、configFlags
どのフェーズがエージェントを使用するか?	フェーズファイルの複雑さ	エージェントプロンプトはそのまま保持する必要がある
TodoWrite の粒度は?	TodoWrite Pattern	サブタスクを持つフェーズもあれば、単一のフェーズもある
計画メモのパターンはあるか?	Post-Phase Updates	フェーズをまたいで蓄積される状態ドキュメント
エラーからの復旧は?	Error Handling	1 回リトライしてから報告、対ロールバック
設定の収集が必要か?	Interactive Preference Collection	SKILL.md の AskUserQuestion で収集し、workflowPreferences として渡す
フェーズ N がフェーズ M に引き継ぐか?	Direct Phase Handoff (Pattern 7)	Skill() ルーティングではなく、フェーズドキュメントを直接読み取る
長時間のコンテキスト後に後続フェーズが実行されるか?	Compact Recovery (Pattern 9)	センチネルとチェックポイントを追加し、Phase Reference テーブルで 🔄 を付ける