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","sync routing tables","routing maintenance","rebuild routing index","routing drift"],"category":"meta-tooling","pairs_with":["toolkit-evolution","generate-claudemd"]}

Routing Table Updater Skill

Overview

This skill maintains /do routing tables and command references 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 safely updates skills/meta/do/SKILL.md, skills/meta/do/references/routing-tables.md, agents/INDEX.json, and commands/*.md files. All changes are backed up before modification, and markdown syntax is validated before commit.

---

Reference Loading Table

Signal	Load These Files	Why
tasks related to this reference	batch-mode.md	Loads detailed guidance from batch-mode.md.
tasks related to this reference	conflict-resolution.md	Loads detailed guidance from conflict-resolution.md.
errors, error handling	error-handling.md	Loads detailed guidance from error-handling.md.
example-driven tasks	examples.md	Loads detailed guidance from examples.md.
implementation patterns	extraction-patterns.md	Loads detailed guidance from extraction-patterns.md.
tasks related to this reference	routing-format.md	Loads detailed guidance from routing-format.md.
example-driven tasks	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.

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 conflicts.

Constraints: Deterministic generation (no randomness); entries follow exact /do format spec (references/routing-format.md); pattern conflicts detected immediately; entries sorted alphabetically; duplicates within same table 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. Load routing format spec from references/routing-format.md
2. Map each capability to appropriate routing table
3. Format entries according to /do table structure
4. Detect pattern conflicts (see references/conflict-resolution.md)
5. Sort entries alphabetically within tables

Step 3: Review conflict detection output

Low-severity conflicts: script applies specificity rules automatically. High-severity conflicts: script blocks gate passage and requires manual resolution.

Gate: All capabilities are mapped, entries follow /do format, conflicts are documented, and no duplicates remain within the same table. Proceed to Phase 4 only after the gate passes. See references/error-handling.md for gate failure recovery.

---

Phase 4A: UPDATE -- Safely Modify commands/do.md

Goal: Apply generated routing entries to do.md with backup and validation.

Constraints: Always create timestamped backup before modification; preserve all hand-written entries (entries without [AUTO-GENERATED] marker are never overwritten); markdown table syntax validates after updates; atomic backup/restore on validation failure.

Step 1: Run update script with backup

python3 ~/.claude/skills/meta/routing-table-updater/scripts/update_routing.py --input routing_entries.json --target $HOME/vexjoy-agent/commands/do.md --backup

Step 2: Verify backup exists

Confirm backup file at commands/.do.md.backup.{timestamp} before any modifications proceed.

Step 3: Review the diff

The script outputs a diff showing new entries (+), modified entries (- old / + new), and preserved manual entries (unchanged). Review for correctness.

Step 4: Confirm or abort

If diff looks correct: confirm to apply. If unexpected: abort and investigate. With --auto-commit: confirmation skipped.

Step 5: Post-update validation

The script validates pipe alignment, header separator rows, consistent column counts, and no orphaned rows. On validation failure: automatic restore from backup. Report error details.

Gate: Backup created, all manual entries preserved, markdown validated, diff confirmed. If gate fails, RESTORE from backup.

---

Phase 4B: UPDATE -- Update Command Files

Goal: Update command files with current skill/agent references.

Constraints: Command files updated only if they reference outdated/invalid skills; backups created for all modified files; all referenced skills must exist; markdown syntax validated after updates.

Step 1: Run update script with backup

python3 ~/.claude/skills/meta/routing-table-updater/scripts/update_commands.py --commands-dir $HOME/vexjoy-agent/commands --metadata metadata.json --backup

Step 2: Understand the update process

1. Scan command files for skill invocations and references
2. Identify outdated or invalid references (renamed/removed skills)
3. Update references to match current metadata
4. Create backups for all modified command files
5. Validate updated markdown syntax

Gate: Backups created for all modified files, all referenced skills exist, markdown validated.

---

Phase 5: VERIFY -- Validate Routing Correctness

Goal: Final validation of all routing tables.

Constraints: All auto-generated entries must have [AUTO-GENERATED] markers; no duplicate patterns within same routing table; all referenced skills/agents must exist; complexity values must match Simple/Medium/Complex; overlapping patterns documented with priority rules.

Step 1: Run validation script

python3 ~/.claude/skills/meta/routing-table-updater/scripts/validate.py --target $HOME/vexjoy-agent/commands/do.md

Step 2: Understand verification checks

1. Structural: All routing tables present, headers formatted, pipes aligned
2. Content: All auto-generated entries marked, no duplicates, all referenced skills/agents exist
3. Conflicts: Overlapping patterns documented, priority rules applied
4. Integration: Sample pattern matching tests pass

Gate: All checks pass. Task complete ONLY if final gate passes. See references/error-handling.md for gate failure recovery.

---

Examples

See references/skill-examples.md for worked examples (new skill created, agent description updated, conflict detection, manual entry preserved).

---

Batch Mode

When invoked by pipeline-scaffolder Phase 4 (INTEGRATE), this skill operates in batch mode to register N skills and 0-1 agents in a single pass.

See references/batch-mode.md for batch input format, batch process, and the batch vs single mode comparison table.

---

Integration

This skill is typically invoked after other creation skills complete:

• After skill-creator: New skill created, routing tables need updated entry
• After skill/agent modification: Description or trigger changes require routing refresh
• During repository maintenance: Periodic sync to catch manual drift
• After pipeline-scaffolder Phase 3: N skills created for a domain, all need routing (batch mode)

Invocation by other skills:

skill: routing-table-updater

The skill reads metadata from all skills and agents but never modifies them. It only writes to skills/meta/do/SKILL.md, skills/meta/do/references/routing-tables.md, agents/INDEX.json, and commands/*.md files.

---

Error Handling

See references/error-handling.md for the full error matrix (YAML parse errors, routing conflicts, manual entry overwrites, markdown validation failures) and per-phase gate failure recovery.

---

References

Reference Files

• ${CLAUDE_SKILL_DIR}/references/routing-format.md: /do routing table format specification (table structure, entry formats, ordering rules)
• ${CLAUDE_SKILL_DIR}/references/extraction-patterns.md: Trigger phrase extraction patterns (regex, keyword maps, complexity inference)
• ${CLAUDE_SKILL_DIR}/references/conflict-resolution.md: Conflict types, priority rules, severity levels, resolution process
• ${CLAUDE_SKILL_DIR}/references/examples.md: Real-world examples of routing table updates (new skill, updated agent, conflict detection, manual preservation)
• ${CLAUDE_SKILL_DIR}/references/skill-examples.md: Worked examples for the 5-phase pipeline (Phase 1-5 walkthroughs)
• ${CLAUDE_SKILL_DIR}/references/batch-mode.md: Batch mode invocation by pipeline-scaffolder (input format, process, comparison)
• ${CLAUDE_SKILL_DIR}/references/error-handling.md: Error matrix and per-phase gate failure recovery