skill-synthesizer

Skill Synthesizer v2

WHAT

Read skill-plan.json (generated by skill-planner and approved by the user), and automatically generate multiple independent Claude Code skills. 1 skill = 1 purpose. Store prompt templates in executable skills, and store foundational concepts in shared knowledge skills.

WHY

• In v1, 1 course = 1 monolithic skill → skills became bloated and trigger accuracy decreased
• The user has already approved the structure in skill-planner → faithfully implement that design
• If each skill is independent, it can be improved, tested, and replaced individually
• An executable skill without a prompt template cannot be executed → assets/ is required

⚠️ Important: Write permission constraints and workarounds

~/.claude/skills/ Direct Write to is blocked by permissions. Always generate via a staging directory.

Generation flow

# 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/

Required instructions when delegating to an Agent

When running skill-synthesizer with an Agent, always specify this in the prompt:

「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

Input files

File	Provided by	Required
skill-plan.json	skill-planner	Yes
knowledge/*.json	concept-extractor	Yes
chapters/*/procedures.json	procedure-extractor	Yes
resources/	resource-fetcher	Conditional
resources-manifest.json	resource-fetcher	Conditional
manuals/*.md path	utage-manual	No (reference only)

Output structure

executable skill (for each skill in the plan):

~/.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              ← 自己検証チェックリスト

---

Processing steps

Step 1: Loading and validating skill-plan.json

BLOCKER: skill-plan.json exists and isapproved: true do not proceed unless

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

Validation items:

Check	Condition
skill-plan.json exists	The file exists
approved flag	true is
skills array	There is one or more skill definitions
name in each skill	In all skills name has a field
type in each skill	executable or shared_knowledge
procedures in each skill	executable has a procedure ID list
concepts in each skill	There is a related concept ID list
trigger_words in each skill	executable has trigger words

When validation fails: Prompt re-execution of skill-planner. If the plan is not approved, ask the user for approval.

Step 2: Collecting source data

Read all 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

If resources/ exists, also readresources-manifest.json .

Step 3: Generating each executable skill

For each type: "executable" About the skill:

3a. Data collection

• procedures Extract the corresponding procedures from chapters/*/procedures.json using the ID list
• concepts Extract the corresponding concepts from knowledge/*.json using the ID list
• resources Identify the corresponding resources from resources/ using the list

3b. Generation of assets/

BLOCKERIf the executable skill has no prompt templates, abort generation

Copy the prompt template from the resource to assets/prompts/ to:

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

If the prompt template does not exist in resources:

• Generate a prompt template from the procedure content in procedures.json
• Template the procedure's steps, inputs, and outputs
• assets/prompts/{procedure-name}.md save as

3c. Generation of SKILL.md

templates/skill-template.md Generate according to the pattern of . The following structure:

---
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. Generation of references/

mkdir -p "${SKILL_DIR}/references"

File	Content
concepts.md	This skill's concepts Only concepts corresponding to IDs
ng-ok.md	Failure patterns specific to this procedure (extracted from tacit_knowledge)

Step 4: Generation of shared knowledge skill

skill-plan.jsonの type: "shared_knowledge" Generate based on entries.

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/

File	Content source
concepts.md	All concepts from all knowledge/*.json (by category)
knowledge-graph.md	Mermaid diagram + table from knowledge-graph.json
key-quotes.md	tacit_knowledge + important quotations
checklist.md	Self-verification checklist across all skills

Step 5: Verification of depends_on

BLOCKER: If there are unresolved depends_on, do not consider generation complete

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}"/*/

Confirm that all depends_on references point to skill directories that actually exist. If there are unresolved references:

1. Check whether the referenced skill is included in the plan
2. If included, it is a generation order issue → continue generation
3. If not included, report an error

Step 6: Confirmation of writing to staging

Confirm that all files are written under STAGING_DIR="${COURSE_BUNDLE_DIR:-$(pwd)}/generated_skills" . ~/.claude/skills/ Do not write directly to .

Step 7: Reporting to the user

Present in the following format:

## 生成結果

### 生成されたスキル

| スキル名 | タイプ | 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}

---

Manual reference rules

Do not copy manuals (manuals/*.md). Reference them by path.

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

Verify whether the manual path actually exists:

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

---

NG/OK table

NG	OK	Reason
Pack all data into one skill	Split as per the plan	1 skill = 1 purpose
Executable without the prompt body	Store templates in assets/	Do not create skills that cannot be executed
Copy the manual	Reference by path	Avoid duplication
Start generation without plan approval	Confirm approval of skill-plan.json	The user decides the configuration
depends_on is unresolved	Verify whether all references actually exist	Zero hidden dependencies
Copy all concepts into each skill	Only related concepts into references/	Centralize in shared_knowledge
Generic NG/OK table	Analyze failure patterns specific to the procedure	Directly tied to practicality

---

Self-verification checklist

After generation is complete, confirm all of the following:

• Whether each skill's SKILL.md is 500 lines or fewer
• Does each executable skill have assets/ or an inline prompt?
• Are all depends_on values names of skills that actually exist?
• Does shared_knowledge include the foundational concepts?
• Are the trigger_words specific to the course?
• Does the manual_ref path actually exist?
• Does each executable skill's references/concepts.md contain only concepts relevant to that skill?
• Does the shared knowledge skill's references/concepts.md contain all concepts?
• Has the corresponding resource from resources-manifest.json been copied to assets/?

---

Out of scope

What not to do	What to use instead
Design and split decisions for skill structure	skill-planner
Importing course videos	course-ingest
Extracting concepts	concept-extractor
Extracting procedures	procedure-extractor
Acquiring resources	resource-fetcher
Generating manuals	utage-manual
Consulting on skill design	teru-skill-creator