create-skill-graph

name	create-skill-graph
description	Create a navigable skill graph for a domain from research output or existing skills/docs. Use when user says /create-skill-graph, wants to organize skills into MOCs, build a knowledge graph, or structure domain docs into a navigable hierarchy. Accepts a domain slug with --from-research or --from-existing flags.
argument-hint	<domain-slug> [--from-research | --from-existing]
metadata	{"author":"shihwesley","version":"1.0.0"}

/create-skill-graph

Creates a navigable skill graph for a domain. Works from two sources:

• From research: uses ~/.claude/research/<slug>/expertise.md + question-tree.md to derive MOCs
• From existing files: inventories .claude/commands/, .claude/skills/, .claude/docs/ and clusters them

Step 1: Detect Source

slug = first argument (e.g., "android-xr", "swift", "agent-infra")

IF ~/.claude/research/<slug>/expertise.md exists:
  source = "research"
  Read expertise.md and question-tree.md
ELSE IF .claude/docs/ or .claude/commands/ have files matching the slug:
  source = "existing"
  Inventory matching files
ELSE:
  Tell user: "No research or existing files found for '<slug>'. Run /research <slug> first."
  Stop.

Step 2: Derive MOC Structure

From research (question-tree.md drives the structure):

• Each top-level branch in the question tree -> candidate MOC
• Branches with <2 sub-questions -> merge into a related MOC
• Branches with >8 sub-questions -> consider splitting
• Target: 5-10 MOCs

From existing files:

• Scan .claude/commands/, .claude/skills/, .claude/docs/, .claude/agents/ for domain-related files
• Cluster by topic (use filenames, frontmatter descriptions, and content keywords)
• Each cluster with 2+ files -> candidate MOC
• Target: 5-10 MOCs

Present the proposed MOC structure to the user:

Proposed skill graph for <slug>:
  1. <moc-name> — <description> (N files)
  2. <moc-name> — <description> (N files)
  ...
Proceed?

Step 3: Build the Graph

Create the directory and files:

.claude/docs/<slug>-graph/
├── index.md            <- Hub with all MOC descriptions
├── <moc-1>.md          <- Each MOC links to skills/docs/agents
├── <moc-2>.md
├── ...
└── traverse.md         <- Copy from swift-graph, adapt domain name

Index format:

---
description: "Hub MOC for <domain>. Entry point for all <domain> skill graph navigation."
updated: <today>
---

# <Domain> Skill Graph

## <MOC Title>
- [[<moc>.md]] — <description>
...

## Navigation Protocol
1. Read this index — pick the MOC(s) matching your task
2. Read the MOC — pick the specific skills/docs you need
3. Read those files — now you have the knowledge to act

MOC format:

---
description: "<one-line description of this MOC's scope>"
keywords: [<relevant keywords>]
---

# <MOC Title>

<Orientation paragraph>

## <Section>
- **Skill/Doc/Agent: `name`** -> `<file path>`
  <one-line description of what this covers and when to use it>

## Cross-References
- Related MOC -> [[<other-moc>.md]]

From research: MOC content comes from the expertise.md sections. Each section's key points become the MOC descriptions. If the research generated a skill or subagent, link those too.

From existing: MOC content links to the inventoried files with descriptions from their frontmatter.

Step 4: Wire Enforcement

After building the graph:

1. Check skill-registry.json — if keywords for this domain exist, add graphPaths entries pointing to the new index.md
2. Check for agents — if domain-specific agents exist (e.g., a research-generated specialist), update their "Before Starting" section to read the graph first
3. Report: list all created files and enforcement points

Step 5: Validate

Run the validation pattern (same as swift-graph-validate.sh but adapted):

• Check all file references resolve
• Check cross-references between MOCs are valid
• Report any issues

Step 6: Report

Skill graph created: .claude/docs/<slug>-graph/
  <N> MOCs, <M> linked files
  Index: .claude/docs/<slug>-graph/index.md
  Enforcement: <what was wired>
  Validation: HEALTHY / <issues>