Skill Synthesizer

Skill Synthesizer v2

WHAT

skill-plan.json（skill-plannerが生成しユーザーが承認済み）を読み込み、 複数の独立したClaude Codeスキルを自動生成する。 1スキル=1目的。executable skillにはプロンプトテンプレートを、 shared knowledgeスキルには基盤概念を格納する。

WHY

• v1は1講座=1モノリシックスキルだった → スキルが肥大化し発火精度が下がる
• skill-plannerでユーザーが構成を承認済み → その設計を忠実に実装する
• 各スキルが独立していれば、個別に改善・テスト・差し替えできる
• プロンプトテンプレートがないexecutable skillは実行不能 → assets/必須

⚠️ 重要: Write権限の制約と回避策

~/.claude/skills/ への直接Writeは権限ブロックされる。 必ずstaging directory経由で生成する。

生成フロー

# Step 1: staging dir に生成
STAGING="${COURSE_BUNDLE_DIR:-$(pwd)}/generated_skills"
mkdir -p $STAGING
# → 全SKILL.md, references/, assets/ をここに書く

# Step 2: ユーザーまたはメインセッションがcpで移動
cp -r $STAGING/* ~/.claude/skills/

Agent委譲時の必須指示

skill-synthesizerをAgentで実行する場合、プロンプトに必ず明記する:

「STAGING OUTPUT: /path/to/generated_skills/ Write all skill files under this staging directory. After completion, the user will move them to ~/.claude/skills/.」

---

HOW

入力ファイル

出力構造

executable skill（計画の各スキルごと）:

~/.claude/skills/{skill-name}/
  SKILL.md                    ← 単一目的、プロンプト埋込またはassets参照
  assets/
    prompts/{template}.md     ← 実際のプロンプトテンプレート本文
  references/
    concepts.md               ← このスキルに関連する概念のみ
    ng-ok.md                  ← このスキル固有の失敗パターン

shared knowledge skill:

~/.claude/skills/{course}-knowledge/
  SKILL.md                    ← インデックス + 基盤概念
  references/
    concepts.md               ← 全概念
    knowledge-graph.md        ← 依存関係マップ
    key-quotes.md             ← 暗黙知・引用
    checklist.md              ← 自己検証チェックリスト

---

処理ステップ

Step 1: skill-plan.json の読み込みと検証

BLOCKER: skill-plan.json が存在し、approved: true でなければ先に進むな

cat "${BUNDLE_DIR}/skill-plan.json" | jq '.approved'

検証項目:

検証失敗時: skill-plannerの再実行を促す。plan未承認ならユーザーに承認を求める。

Step 2: ソースデータの収集

全 knowledge/*.json と chapters/*/procedures.json を読み込む。

# 概念の総数確認
find "${BUNDLE_DIR}/knowledge" -name "*.json" -exec cat {} \; | jq '[.concepts[]] | length' 2>/dev/null

# 手順の総数確認
find "${BUNDLE_DIR}/chapters" -name "procedures.json" -exec cat {} \; | jq '[.procedures[]] | length' | paste -sd+ | bc

resources/ が存在する場合、resources-manifest.json も読み込む。

Step 3: 各executable skillの生成

skill-plan.jsonの各 type: "executable" スキルについて:

3a. データ収集

• procedures IDリストから該当手順を chapters/*/procedures.json から抽出
• concepts IDリストから該当概念を knowledge/*.json から抽出
• resources リストから該当リソースを resources/ から特定

3b. assets/ の生成

BLOCKER: executable skillにプロンプトテンプレートが1つもない場合、生成を中止

リソースからプロンプトテンプレートを assets/prompts/ にコピー:

mkdir -p "${SKILL_DIR}/assets/prompts"
# resources-manifest.json の該当エントリからコピー
cp "${BUNDLE_DIR}/resources/${resource_file}" "${SKILL_DIR}/assets/prompts/"

プロンプトテンプレートがresourcesに存在しない場合:

• procedures.jsonの手順内容からプロンプトテンプレートを生成
• 手順のステップ・入力・出力をテンプレート化
• assets/prompts/{procedure-name}.md として保存

3c. SKILL.md の生成

templates/skill-template.md のパターンに従い生成。以下の構造:

---
name: {skill_name}
description: "{purpose}。「{trigger_words}」で発動。"
---

# {skill_name}

## WHAT
{purpose} を実行する。

## WHY
{rationale}

## HOW

### 入力
{input description from plan}

### 手順
{steps from procedures.json}
各ステップでプロンプトテンプレートを参照:
> このステップのテンプレート: `assets/prompts/{template}.md`

> BLOCKER: {critical check from procedures}

### 出力
{output description from plan}

## NG/OK テーブル
{skill-specific failure patterns from concepts + procedures}

## 自己検証チェックリスト
{skill-specific checks}

## 詳細な解説
画像付きの詳細説明: `{manual_ref}`

## 依存
- {depends_on skill name}: {why}

3d. references/ の生成

mkdir -p "${SKILL_DIR}/references"

Step 4: shared knowledge skillの生成

skill-plan.jsonの type: "shared_knowledge" エントリに基づき生成。

4a. SKILL.md

---
name: {course}-knowledge
description: "{course}の基盤概念・ナレッジグラフ・暗黙知を提供。他のスキルが概念を参照する際に使用。「{course}の概念」「{course}のナレッジ」で発動。"
---

# {course} Knowledge Base

## WHAT
{course}の全概念・暗黙知・知識グラフを集約し、
他のexecutable skillが参照するナレッジハブとして機能する。

## WHY
- 概念定義を各スキルに重複させない
- 概念間の依存関係を一元管理する
- 暗黙知・引用を保全する

## 概念インデックス
{全概念の名前・カテゴリ・簡潔な定義のテーブル}

## 参照ファイル
| ファイル | 内容 | いつ読むか |
|---------|------|----------|
| `references/concepts.md` | 全概念の詳細 | 概念を深掘りするとき |
| `references/knowledge-graph.md` | 依存関係マップ | 前提を確認するとき |
| `references/key-quotes.md` | 暗黙知・引用 | 根拠が必要なとき |
| `references/checklist.md` | 自己検証チェックリスト | 品質確認時 |

4b. references/

Step 5: depends_on の検証

BLOCKER: 未解決のdepends_onがあれば生成完了としない

STAGING_DIR="${COURSE_BUNDLE_DIR:-$(pwd)}/generated_skills"

# 生成された全SKILL.mdからdepends_onを抽出
grep -r "^- " "${STAGING_DIR}"/*/SKILL.md | grep "depends_on"

# stagingに存在するスキル名のリスト
ls -d "${STAGING_DIR}"/*/

全depends_on参照が実在するスキルディレクトリを指していることを確認。 未解決の参照があれば: 1. 参照先スキルがplanに含まれているか確認 2. 含まれていれば生成順序の問題 → 生成を続行 3. 含まれていなければエラー報告

Step 6: staging への書き出し確認

全ファイルが STAGING_DIR="${COURSE_BUNDLE_DIR:-$(pwd)}/generated_skills" 以下に書かれていることを確認する。 ~/.claude/skills/ への直接書き込みは行わない。

Step 7: ユーザーへの報告

以下の形式で提示:

## 生成結果

### 生成されたスキル

| スキル名 | タイプ | SKILL.md行数 | assets数 | depends_on |
|---------|--------|-------------|---------|-----------|
| {name}  | executable | {lines} | {count} | {deps}    |
| {name}-knowledge | shared | {lines} | - | - |

### 検証結果
- [ ] 全SKILL.mdが500行以下: {result}
- [ ] 全executable skillにassets/またはインラインプロンプトあり: {result}
- [ ] 全depends_onが実在するスキル名: {result}
- [ ] shared_knowledgeに基盤概念あり: {result}
- [ ] trigger_wordsが講座固有: {result}
- [ ] manual_refのパスが実在: {result}

### ファイル一覧
{generated file tree}

---

マニュアル参照ルール

マニュアル（manuals/*.md）はコピーしない。パスで参照する。

## 詳細な解説
画像付きの詳細説明: `{BUNDLE_DIR}/manuals/{chapter}.md`

マニュアルパスが実在するかを検証:

test -f "${BUNDLE_DIR}/manuals/${manual_file}" && echo "OK" || echo "MISSING"

---

NG/OK テーブル

---

自己検証チェックリスト

生成完了後、以下をすべて確認:

• [ ] 各スキルのSKILL.mdが500行以下か
• [ ] 各executable skillにassets/またはインラインプロンプトがあるか
• [ ] depends_onが全て実在するスキル名か
• [ ] shared_knowledgeに基盤概念が含まれているか
• [ ] trigger_wordsが講座固有か
• [ ] manual_refのパスが実在するか
• [ ] 各executable skillのreferences/concepts.mdがそのスキルの関連概念のみ含むか
• [ ] shared knowledge skillのreferences/concepts.mdが全概念を含むか
• [ ] resources-manifest.jsonの該当リソースがassets/にコピーされているか

---

スコープ外

Synthesis Strategy v2: Multi-Skill Generation

skill-plan.jsonに基づき複数の独立スキルを生成する際の詳細戦略。

1. v1からの変更点

2. skill-plan.jsonの構造

{
  "course_name": "おさるAIマーケティング",
  "approved": true,
  "skills": [
    {
      "name": "osaru-funnel-builder",
      "type": "executable",
      "purpose": "ファネル構築の実行",
      "trigger_words": ["ファネル構築", "funnel build", "導線設計"],
      "procedures": ["proc_001", "proc_002"],
      "concepts": ["funnel", "lead_generation", "opt_in"],
      "resources": ["funnel-template.md"],
      "manual_ref": "manuals/chapter03.md",
      "depends_on": ["osaru-knowledge"],
      "rationale": "ファネル構築は独立した実行単位として最も頻繁に使われる"
    },
    {
      "name": "osaru-knowledge",
      "type": "shared_knowledge",
      "purpose": "基盤概念の一元管理",
      "concepts": ["all"],
      "rationale": "概念定義の重複を防ぎ、一元管理する"
    }
  ]
}

3. 概念の分配戦略

shared knowledge skill

全概念を格納する。knowledge-graph.jsonの依存関係分析を行い:

基盤概念 = depended_by_count 上位30% or 被依存3件以上

基盤概念はSKILL.md本文の概念インデックスに要約を掲載。 全概念の詳細は references/concepts.md に格納。

executable skill

skill-plan.jsonの concepts リストに該当する概念のみを references/concepts.md に格納する。

判定フロー:

1. skill-plan.jsonの concepts IDリストを取得
2. knowledge/*.jsonから該当IDの概念を抽出
3. 該当概念のみ references/concepts.md に書き出す
4. SKILL.md本文には概念定義を書かない（shared knowledgeを参照）

4. プロンプトテンプレートの配置

リソースからの取得

resources-manifest.json の該当エントリ
  → resources/{file} をそのまま assets/prompts/ にコピー

手順からの生成

リソースにプロンプトテンプレートがない場合:

procedures.json の手順
  → ステップ・入力・出力をテンプレート化
  → assets/prompts/{procedure-name}.md として生成

テンプレートの構造

# {テンプレート名}

## 目的
{このプロンプトで何を達成するか}

## 入力変数
| 変数 | 説明 | 例 |
|------|------|-----|
| {{var1}} | ... | ... |

## プロンプト本文

{実際のプロンプトテキスト}

## 期待される出力
{出力の形式・構造}

5. depends_on の設計

依存の種類

検証アルゴリズム

1. 生成された全スキルのdepends_on を収集
2. 生成された全スキルの name を収集
3. depends_on の各エントリが name リストに存在するか確認
4. 未解決があればエラー報告（生成完了としない）

6. NG/OKテーブルの生成戦略

共通パターン（全スキルに適用しない）

v1では汎用NG/OKを全スキルに適用していた。 v2では各スキルの手順・概念から固有のパターンを生成する。

生成手順

1. 該当手順の tacit_knowledge を抽出
2. 「〜してはいけない」「〜は間違い」の表現を NG 列に
3. 「代わりに〜」「正しくは〜」の表現を OK 列に
4. 理由を teaching_patterns から補完
5. スキル固有でないパターンは除外

7. マニュアル参照ルール

マニュアルは参照専用。コピーしない。

正しい参照

## 詳細な解説
画像付きの詳細説明: `{BUNDLE_DIR}/manuals/chapter03.md`

やってはいけないこと

• マニュアルの内容をSKILL.mdにコピペ
• マニュアルの画像をassets/にコピー
• マニュアルの手順をproceduresの代わりに使う

検証

# manual_refが実在するか確認
for ref in $(cat skill-plan.json | jq -r '.skills[].manual_ref // empty'); do
  test -f "${BUNDLE_DIR}/${ref}" && echo "OK: ${ref}" || echo "MISSING: ${ref}"
done

8. 500行制限の管理

executable skill の行数配分

shared knowledge skill の行数配分

概念数が多い場合（50件超）:

• インデックスにはカテゴリ別の件数サマリーのみ
• 個別概念は全て references/concepts.md へ

Concepts Template

references/concepts.md 生成時のテンプレート。

---

# {{course_name}} - 概念リファレンス

> このファイルは `SKILL.md` の補足資料です。特定の概念を深掘りする際に参照してください。

## 概要

- 総概念数: {{total_concepts}}
- カテゴリ数: {{category_count}}
- 基盤概念: {{foundational_count}}件（SKILL.md本文にも記載）

---

{{#each categories}}
## カテゴリ: {{category_name}}

{{#each concepts}}
### {{concept_name}}

**分類**: {{classification}}（基盤 / 補助 / 詳細）
**チャプター**: {{source_chapter}}
**被依存数**: {{depended_by_count}}

#### 定義

{{definition}}

#### 具体例

{{#each examples}}
- {{example}}
{{/each}}

#### 重要引用

{{#each key_quotes}}
> "{{quote}}"
> — {{source}} ({{timestamp}})
{{/each}}

#### 関連概念

| 概念 | 関係 |
|------|------|
{{#each related}}
| {{name}} | {{relation}} |
{{/each}}

#### 暗黙知・補足

{{tacit_knowledge}}

---

{{/each}}
{{/each}}

---

テンプレート使用時の注意

データマッピング

カテゴリの並び順

1. 基盤概念を含むカテゴリを先頭に 2. カテゴリ内では depended_by_count 降順 3. 同数の場合はチャプター順

品質チェック

• [ ] 全概念に定義があるか
• [ ] 基盤概念には必ず具体例があるか
• [ ] 引用にはtimestampが付いているか
• [ ] 関連概念テーブルが空でないか（孤立概念は要確認）

Procedures Template

references/procedures.md 生成時のテンプレート。

---

# {{course_name}} - 手順リファレンス

> このファイルは `SKILL.md` の補足資料です。手順を実行する際に参照してください。

## 概要

- 総手順数: {{total_procedures}}
- 主要手順（SKILL.md記載）: {{main_procedure_count}}件
- 補助手順: {{sub_procedure_count}}件

---

{{#each procedures}}
## {{procedure_name}}

**ID**: {{procedure_id}}
**複雑度**: {{complexity}}（low / medium / high）
**チャプター**: {{source_chapter}}
**関連概念**: {{related_concepts}}
**タグ**: {{tags}}

### 目的

{{objective}}

### 前提条件

{{#each prerequisites}}
- [ ] {{condition}}
{{/each}}

### 手順

{{#each steps}}
#### Step {{step_number}}: {{step_title}}

{{step_description}}

{{#if screenshot}}
**参考スクリーンショット**: `assets/selected_screenshots/{{screenshot}}`
{{/if}}

{{#if blocker}}
> **BLOCKER**: {{blocker_condition}}
> {{blocker_message}}
{{/if}}

{{#if warning}}
> **WARNING**: {{warning}}
{{/if}}

{{/each}}

### 期待される成果

{{outcome}}

### よくある失敗

| 失敗パターン | 原因 | 対処法 |
|------------|------|--------|
{{#each common_failures}}
| {{pattern}} | {{cause}} | {{solution}} |
{{/each}}

---

{{/each}}

---

テンプレート使用時の注意

データマッピング

手順の並び順

1. SKILL.mdに記載された主要手順を先頭に 2. 次に complexity = "high" → "medium" → "low" の順 3. 同じ complexity 内ではチャプター順

スクショの紐づけ

visual-index.jsonの related_procedures フィールドでマッチング:

• マッチするスクショが複数ある場合: value_rating が最も高いものを選択
• マッチするスクショがない場合: スクショなしで記載（無理に追加しない）

BLOCKERの配置基準

procedures.jsonから以下を検出してBLOCKERに変換:

• is_critical: true のステップ
• reversible: false のステップ
• 前提条件チェックを含むステップ

品質チェック

• [ ] 全手順に目的が記載されているか
• [ ] 前提条件が具体的か（「準備する」ではなく「Xをインストールする」）
• [ ] 各ステップが実行可能な粒度か
• [ ] 期待される成果が検証可能な形で書かれているか
• [ ] よくある失敗テーブルに対処法があるか

Executable Skill Template

生成するexecutable skillのSKILL.mdテンプレート。{{placeholder}} を実データで置換する。

---

---
name: {{skill_name}}
description: "{{purpose}}。「{{trigger_words}}」で発動。"
---

# {{skill_display_name}}

## WHAT

{{purpose}} を実行する。

## WHY

{{rationale}}

**このスキルではないもの**:
{{anti_selection}}

## HOW

### 入力

| 項目 | 説明 | 必須 |
|------|------|------|
{{#each inputs}}
| {{name}} | {{description}} | {{required}} |
{{/each}}

### 手順

{{#each steps}}
#### Step {{step_number}}: {{step_name}}

{{step_description}}

{{#if has_template}}
> このステップのテンプレート: `assets/prompts/{{template_name}}.md`
{{/if}}

{{#if has_blocker}}
> **BLOCKER**: {{blocker_condition}}
{{/if}}

{{/each}}

### 出力

| 項目 | 説明 |
|------|------|
{{#each outputs}}
| {{name}} | {{description}} |
{{/each}}

---

## NG/OK テーブル

| NG | OK | 理由 |
|----|-----|------|
{{#each ng_ok_rows}}
| {{ng}} | {{ok}} | {{reason}} |
{{/each}}

---

## 自己検証チェックリスト

{{#each verification_items}}
- [ ] {{item}}
{{/each}}

---

## 詳細な解説

画像付きの詳細説明: `{{manual_ref}}`

---

## 依存

{{#each dependencies}}
- {{skill_name}}: {{reason}}
{{/each}}

---

## 参照ファイル

| ファイル | 内容 | いつ読むか |
|---------|------|----------|
| `assets/prompts/*.md` | プロンプトテンプレート | 手順実行時 |
| `references/concepts.md` | 関連概念の詳細 | 概念を深掘りするとき |
| `references/ng-ok.md` | 拡張NG/OKパターン | 品質改善時 |

---

Shared Knowledge Skill Template

---
name: {{course}}-knowledge
description: "{{course}}の基盤概念・ナレッジグラフ・暗黙知を提供。他のスキルが概念を参照する際に使用。「{{course}}の概念」「{{course}}のナレッジ」「{{course}}の知識」で発動。"
---

# {{course}} Knowledge Base

## WHAT

{{course}}の全概念・暗黙知・知識グラフを集約し、
他のexecutable skillが参照するナレッジハブとして機能する。

## WHY

- 概念定義を各スキルに重複させない
- 概念間の依存関係を一元管理する
- 暗黙知・引用を保全する

## 概念インデックス

| カテゴリ | 概念名 | 簡潔な定義 |
|---------|--------|-----------|
{{#each concepts}}
| {{category}} | {{name}} | {{brief_definition}} |
{{/each}}

## 参照ファイル

| ファイル | 内容 | いつ読むか |
|---------|------|----------|
| `references/concepts.md` | 全概念の詳細定義・例・引用 | 概念を深掘りするとき |
| `references/knowledge-graph.md` | 概念間の依存関係マップ | 前提を確認するとき |
| `references/key-quotes.md` | 暗黙知・重要引用 | 根拠が必要なとき |
| `references/checklist.md` | 自己検証チェックリスト | 品質確認時 |

---

テンプレート使用時の注意

placeholderの置換ルール

BLOCKER配置の判断基準

手順中に以下の条件があればBLOCKERを配置:

1. 不可逆操作の直前: やり直しが困難なステップ 2. 前提条件の確認: 必要な準備が整っていないと後続が無駄になるステップ 3. 品質ゲート: 出力品質が基準を満たさないと先に進むべきでないステップ 4. 外部依存: 外部サービスやユーザー入力が必要なステップ

行数管理

生成後に wc -l SKILL.md で行数を確認。500行を超えた場合:

1. 手順の詳細ステップをassets/に移動 2. NG/OKテーブルの行をreferences/ng-ok.mdに退避（主要5行のみ残す） 3. WHYセクションを簡潔にする 4. 概念詳細をreferences/concepts.mdに完全委譲