skill-taxonomy

name

skill-taxonomy

description

Scan, classify, and visualize all skills in the workspace. Produces an interactive HTML report with two views — a layered dependency graph and a structured analysis panel showing routing conflicts, layer violations, duplicate capabilities, missing abstractions, and a prioritized action plan. Use when the user wants to audit skill organization, reduce routing errors, understand skill dependencies, or plan a skill consolidation. Trigger on: skill map, skill graph, skill audit, skill organization, routing optimization, skill overlap, skill layers, skill dependencies.

Skill Taxonomy Analyzer

Scan all skills in the workspace, classify them into layers, map dependencies, run a routing/efficiency analysis, and produce an interactive HTML report.

---

Step 1 — Scan All Skills

Skills live in multiple locations. Scan all of:

Location	Pattern
Root skills	skills/*/SKILL.md
Workspace skills	workspaces/*/skills/*/SKILL.md
Nested sub-skills	skills/*/*/SKILL.md (recursive)
Project/product skills	workspaces/*/products/*/SKILL.md, workspaces/*/*/SKILL.md

For each SKILL.md found, extract from frontmatter:

• name, description
• Infer workspace from path (workspaces/<ws>/ → ws name; otherwise root)

From the body, extract:

• Mentions of other skill names (dependencies)
• External systems (MySQL, browser, Slack, Feishu, Stripe, GitHub, MCP, SSH, etc.)
• Whether it has scripts (check scripts/ sibling dir)
• Whether it's deprecated (keyword in description or body)

Skip: _shared/, references/, files starting with _, archive dirs.

---

Step 2 — Classify Into Layers

Assign every skill to one of three layers:

Layer	Name	What belongs here
L0	Infrastructure & Connectors	Connects to external systems. Provides generic capability. No business logic. Examples: browser automation, SSH, DB query engine, email SMTP, file storage, MCP bridge, media processing, secret management
L1	Domain Knowledge & Data	Encodes business rules, metrics definitions, calibration standards, query templates for a specific domain. Retrieves/transforms domain data. Does not orchestrate multi-step workflows
L2	Task & Workflow Orchestration	Runs an end-to-end workflow. Coordinates multiple steps, sub-agents, or other skills. Produces a final deliverable (report, published page, PR, audit, campaign)

Classification heuristics:

• Ask: what does this skill PRODUCE?
  • A connection / raw data stream → L0
  • Domain metrics / structured domain data → L1
  • A completed task output / deliverable → L2
• Communication skills (email inboxes, Slack) = L0 — they are transport connectors
• Meta-skills (skill-creator, clawhub) = L0
• If a skill spans layers, assign the primary purpose layer and note the secondary

---

Step 3 — Map Dependencies

For each skill, record:

• Explicit deps: other skill names mentioned in the body
• Implicit deps: if the skill uses an external system that another skill owns (e.g., uses MySQL → implicitly depends on the DB connector skill)
• Consumers: which skills depend on this one

Valid dependency directions: L2 → L1 → L0 and L2 → L0. Flag any upward dependency (lower layer calling higher) as a violation.

---

Step 4 — Run Routing & Efficiency Analysis

Compute all six analysis dimensions below. Be systematic — check every skill pair for conflicts, every skill for violations.

4a. Routing Conflicts

Two skills conflict when the same user phrase could reasonably trigger either. Detection signals:

• Shared keywords in description (especially nouns: tool names, domain terms, action verbs)
• Same external system + same action type
• Near-identical names differing only by workspace

For each conflict:

skills: [id1, id2, ...]        # the conflicting group
overlap: "exact overlap description"
severity: critical | high | medium | low
recommendation: "concrete fix"

Severity rules:

• critical: >50% of realistic user prompts are ambiguous between them
• high: significant overlap, router will regularly misfire
• medium: overlap in edge cases, requires clarifying turn ~30% of the time
• low: theoretical overlap only

4b. Layer Violations

Flag when:

• A skill calls upward (L0 calling L2)
• An L2 skill bypasses an available L1 skill and goes directly to L0 (skipping an existing abstraction)
• A skill is misclassified (acts as L0 but placed in L1, etc.)

skill: "id"
issue: "description of the violation"
severity: high | medium | low
recommendation: "fix"

4c. Duplicate Capabilities

Two or more skills do the same thing when:

• Same external system + same operation type appear in both descriptions
• One is a workspace copy of a root skill with no meaningful additions
• One is already marked deprecated but still present

skills: [id1, id2, ...]
issue: "what is duplicated"
severity: high | medium | low
recommendation: "merge strategy"

4d. Missing Abstractions

A pattern exists when 3+ skills independently implement the same external system connection or sub-workflow that could be extracted into a shared skill.

pattern: "N skills independently do X"
affected_skills: [id1, id2, ...]
recommendation: "extract to new L0/L1 skill named Y"

4e. Proposed Actions

Derive concrete actions from the findings above. Use these action types:

Type	When to use
merge	Two+ skills with duplicate/overlapping capability → one
extract	Shared pattern across 3+ skills → new standalone skill
reclassify	Skill in wrong layer
deprecate	Dead skill, superseded, should be removed
rewrite_description	Routing conflict solvable by description change only
split	One skill doing two unrelated things → two skills

For each action:

type: merge | extract | reclassify | deprecate | rewrite_description | split
skills: [ids of affected skills]
into: "name of resulting skill (if merge/extract)"
reason: "why this action"
impact: "what improves: N skills removed / N routing conflicts resolved / etc."

Order actions by impact × urgency — high-severity conflicts with easy fixes first.

4f. Metrics

Compute three scores (0–100 or percentage):

• health_score (0–100): 100 - (10 × critical_conflicts) - (5 × high_conflicts) - (3 × medium_conflicts) - (2 × duplicates) - (2 × violations)
• routing_clarity (percentage): estimated % of user queries that will route correctly on first try, based on conflict coverage
• layer_compliance (percentage): (skills with valid layer placement / total skills) × 100

4g. Efficiency Summary

Write 3–5 sentences covering:

1. Overall landscape (total skills, workspace distribution, layer balance)
2. The primary bottleneck (what's causing the most routing failures)
3. The highest-leverage fix
4. Expected improvement after applying proposed actions

---

Step 5 — Write the JSON

Write analysis data to /tmp/skill-taxonomy-data.json:

{
  "skills": [
    {
      "id": "unique-id",
      "name": "Display Name",
      "layer": 0,
      "workspace": "root | kaworu | rei | ...",
      "description": "one-line purpose",
      "dependencies": ["other-skill-id"],
      "external_systems": ["MySQL", "Browser"],
      "tags": ["tag1", "tag2"],
      "deprecated": false
    }
  ],
  "analysis": {
    "metrics": {
      "health_score": 75,
      "routing_clarity": "80%",
      "layer_compliance": "90%"
    },
    "efficiency_summary": "...",
    "routing_conflicts": [ ... ],
    "layer_violations": [ ... ],
    "duplicate_capabilities": [ ... ],
    "missing_abstractions": [ ... ],
    "proposed_actions": [ ... ]
  }
}

---

Step 6 — Generate the HTML

python3 skills/skill-taxonomy/scripts/generate_graph.py \
  --input /tmp/skill-taxonomy-data.json \
  --output /tmp/skill-taxonomy-graph.html

Then open:

open /tmp/skill-taxonomy-graph.html

The HTML has two views toggled in the header:

• Graph — swimlane layout (L2 top, L1 middle, L0 bottom), workspace filter tabs, click a card to see its dependency chain highlighted
• Analysis — score dashboard + all six analysis sections; clicking a skill chip jumps to its card in Graph view

---

Output to User

After generating the HTML, present a concise summary in chat:

## Skill Taxonomy Report

**N skills** across M workspaces — L0: X · L1: Y · L2: Z
Health: {score} · Routing clarity: {pct} · Layer compliance: {pct}

### Top Issues
1. [highest severity conflict or violation]
2. [second]
3. [third]

### Highest-Leverage Actions
1. [action with biggest impact]
2. [second]

Full interactive report: open /tmp/skill-taxonomy-graph.html

---

Notes

• The analysis is semantic, not mechanical — read every description carefully before assigning layer or detecting conflicts
• When unsure about layer: ask "does this skill know what the business means by the data?" → yes = L1, no = L0
• A workspace copy of a root skill is a duplicate unless it has meaningfully different calibration, scope, or credentials
• Proposed actions should be actionable immediately — no vague "consider refactoring"
• Deprecated skills still in the directory count against health score until physically removed