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 が存在し、生成対象スキルの status が approved で なければ先に進むな（planレベルの承認フラグではなくスキル単位のstatusで判定する。 proposed / rejected のスキルは生成しない）。 生成完了したスキルは skill-plan.json の該当エントリを status: "generated" に更新すること。

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/にコピーされているか

スコープ外