/routing-table-updater

name: routing-table-updater
description: "Maintain /do routing tables when skills or agents change."
user-invocable: false
allowed-tools:
  - Read
  - Write
  - Bash
  - Grep
  - Glob
  - Edit
  - Task
  - Skill
routing:
  triggers:
    - "update routing tables"
    - "sync routing tables"
    - "routing maintenance"
    - "rebuild routing index"
    - "routing drift"
  not_for: "fleet-wide routing policy, trigger governance, or standards enforcement (use the toolkit-governance-engineer agent). This skill mechanically regenerates and repairs the INDEX files."
  category: meta-tooling
  pairs_with:
    - toolkit-evolution
    - generate-claudemd

Routing Table Updater Skill

Overview

This skill maintains the /do routing indices when skills or agents are added, modified, or removed. It implements a **Phase-Gated Pipeline** -- scan, extract, generate, update, verify -- with deterministic script execution at each phase.

The skill reads metadata from all skills and agents (never modifies them) and validates and repairs the generated routing indices `skills/INDEX.json` and `agents/INDEX.json`. PostToolUse hooks (`hooks/posttooluse-sync-skill-index.py`, `hooks/posttooluse-sync-agent-index.py`) regenerate the indices automatically on every SKILL.md or agent-file edit; this skill covers drift those hooks miss (bulk changes, deletes outside the harness, corrupted index files).

---

Reference Loading Table

| Signal | Load These Files | Why | |---|---|---| | batch registration of many skills (invoked by pipeline-scaffolder) | `batch-mode.md` | Loads detailed guidance from `batch-mode.md`. | | resolving trigger conflicts: priority rules and severity levels | `conflict-resolution.md` | Loads detailed guidance from `conflict-resolution.md`. | | errors, error handling | `error-handling.md` | Loads detailed guidance from `error-handling.md`. | | worked update scenarios: new skill, conflict, manual entry, complexity change | `examples.md` | Loads detailed guidance from `examples.md`. | | extracting trigger phrases: 'use when' clauses, action verbs, domain keywords, complexity inference | `extraction-patterns.md` | Loads detailed guidance from `extraction-patterns.md`. | | routing entry format: frontmatter routing block fields, INDEX.json entry shape, regeneration | `routing-format.md` | Loads detailed guidance from `routing-format.md`. | | skill-entry examples for registering a newly created skill | `skill-examples.md` | Loads detailed guidance from `skill-examples.md`. |

Instructions

Phase 1: SCAN -- Discover All Skills and Agents

**Goal**: Find every skill and agent file in the repository.

**Constraints**: Repository must be at agents toolkit root (requires `commands/do.md`); only scan `skills/*/SKILL.md` and `agents/*.md` formats; file permissions must allow reading.

**Step 1: Run scan script**

python3 ~/.claude/skills/meta/routing-table-updater/scripts/scan.py --repo $HOME/vexjoy-agent

**Step 2: Validate scan output**

Expected output is JSON with `skills_found`, `agents_found`, `skills` (array of paths to skills/*/SKILL.md), `agents` (array of paths to agents/*.md).

**Step 3: Check for gaps**

Compare discovered count against expected. If missing, check directory naming, agent file naming, or file permissions.

**Gate**: All skill directories and agent files are discovered without permission errors. Proceed to Phase 2 only after the gate passes. See `references/error-handling.md` for gate failure recovery.

---

Phase 2: EXTRACT -- Parse Metadata

**Goal**: Extract YAML frontmatter, trigger patterns, complexity, and routing table targets from every discovered file.

**Constraints**: YAML frontmatter must be valid; required fields (`name`, `description`) must be present; trigger patterns extracted from description text; complexity inference must follow `references/extraction-patterns.md`.

**Step 1: Run extraction script**

python3 ~/.claude/skills/meta/routing-table-updater/scripts/extract_metadata.py --input scan_results.json --output metadata.json

**Step 2: Verify extraction completeness**

For each capability, confirm extracted fields: `name`, `description`, `trigger_patterns` (skills), `domain_keywords` (agents), `complexity` (Simple, Medium, Complex), `routing_table` (Intent Detection, Task Type, Domain-Specific, or Combination).

**Step 3: Validate trigger pattern quality**

Review against `references/extraction-patterns.md`. Patterns must be specific enough to avoid false matches, broad enough to catch common phrasings, and free of generic terms.

**Description trimming**: skill descriptions trim safely to ≤40 router-line tokens when the frontmatter `routing.triggers` array stays untouched — triggers carry routing weight independently of the description. Verify trims with `scripts/skill-sprawl-audit.py` plus the routing-benchmark and trigger-ambiguity CI jobs (evidence: PR #801, 11 trims, routing-benchmark 68/68).

**Gate**: All YAML parsed successfully, required fields are present, trigger patterns are extracted for skills, and domain keywords are extracted for agents. Proceed to Phase 3 only after the gate passes. See `references/error-handling.md` for gate failure recovery.

---

Phase 3: GENERATE -- Create Routing Table Entries

**Goal**: Map extracted metadata to routing entries and detect trigger conflicts before the indices are rebuilt.

**Constraints**: Deterministic generation (no randomness); pattern conflicts detected immediately; entries sorted alphabetically; duplicates within the same group block gate passage.

**Step 1: Run generation script**

python3 ~/.claude/skills/meta/routing-table-updater/scripts/generate_routes.py --input metadata.json --output routing_entries.json

**Step 2: Understand the generation process**

1. Group each capability by the routing classification extracted in Phase 2 2. Detect pattern conflicts (see `references/conflict-resolution.md`) 3. Sort entries alphabetically within