Routing Table Updater Skill

Operator Context

Hardcoded Behaviors (Always Apply)

• CLAUDE.md Compliance: Read and follow repository CLAUDE.md before execution. Project instructions override default skill behaviors.
• Over-Engineering Prevention: Only update routing tables that need changes. Keep routing entries concise and pattern-focused. No speculative patterns or flexibility that was not requested. Generate exactly what /do needs -- no additional features.
• Preserve Manual Entries: Detect and skip hand-written routing entries in do.md. Never overwrite entries without

  [AUTO-GENERATED]

  markers.
• Backup Before Modification: Always create timestamped backup of commands/do.md before any changes. Rollback on validation failure.
• Markdown Syntax Validation: Verify table syntax after updates. Ensure pipe alignment and proper header separation.
• Deterministic Generation: Same skill/agent metadata always produces same routing entry. No randomness in pattern extraction or table formatting.

Default Behaviors (ON unless disabled)

• Communication Style: Report facts without self-congratulation. Show diff of routing changes rather than describing them.
• Temporary File Cleanup: Remove temporary metadata JSON files and diff files at completion. Keep only backups and updated do.md.
• Interactive Confirmation: Show diff and ask for confirmation before updating do.md (unless --auto-commit flag provided).
• Progress Reporting: Stream updates as scanning, extracting, generating, and updating phases execute.
• Conflict Detection: Warn when multiple routes match the same pattern with suggestions for resolution.
• Alphabetical Ordering: Maintain alphabetical order within routing tables.

Optional Behaviors (OFF unless enabled)

• Auto-Commit Mode:

  --auto-commit

  flag to skip confirmation and automatically commit changes.
• Dry-Run Mode:

  --dry-run

  to show changes without modifying do.md.
• Verbose Debug:

  --verbose

  for detailed parsing and generation logs.

What This Skill CAN Do

• Scan all skills (skills//SKILL.md) and agents (agents/.md) for metadata
• Extract YAML frontmatter (name, description, version) and trigger patterns
• Generate routing table entries following /do format specification
• Detect routing conflicts (same trigger mapped to multiple routes)
• Safely update commands/do.md with atomic backup/restore
• Update command files (commands/*.md) with skill/agent references
• Preserve all hand-written manual routing entries
• Validate markdown table syntax after updates
• Batch mode: Process N skills at once from a Pipeline Spec or component list (used by pipeline-scaffolder Phase 4)
• INDEX.json updates: Add/update agent entries in

  agents/INDEX.json

  alongside routing tables

What This Skill CANNOT Do

• Infer trigger patterns from vague descriptions (requires explicit phrases)
• Create new routing table sections (only updates existing tables)
• Resolve high-severity conflicts automatically (requires manual priority decisions)
• Modify skill/agent metadata (read-only access to capabilities)
• Handle non-standard markdown table formats

Prerequisites

• Must be in agents repository root (has commands/do.md)
• Skills must have valid YAML frontmatter in SKILL.md files
• Agents must have valid YAML frontmatter in agents/*.md files
• commands/do.md must have routing table sections with standard headers

Instructions

Phase 1: SCAN -- Discover All Skills and Agents

python3 ~/.claude/skills/routing-table-updater/scripts/scan.py --repo $HOME/claude-code-toolkit

• skills_found

  : count of discovered skill files

• agents_found

  : count of discovered agent files

• skills

  : array of paths to skills/*/SKILL.md

• agents

  : array of paths to agents/*.md

• Directory naming (must be skills/*/SKILL.md format)
• Agent file naming (must be agents/*.md format)
• File permissions

• "Repository not found": Verify --repo path points to agents directory
• "No skills found": Check skills/ directory exists and has subdirectories
• "Permission denied": Verify file read permissions

Phase 2: EXTRACT -- Parse Metadata

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

• name

  : Matches YAML frontmatter name field

• description

  : Full description text

• version

  : Semantic version string

• trigger_patterns

  (skills): Array of quoted phrases from description

• domain_keywords

  (agents): Array of technology/domain terms

• complexity

  : Inferred level (Simple, Medium, Complex)

• routing_table

  : Target table (Intent Detection, Task Type, Domain-Specific, or Combination)

references/extraction-patterns.md

• Specific enough to avoid false matches
• Broad enough to catch common phrasings
• Free of generic terms that match too many routes

• "Invalid YAML in {file}": Fix YAML frontmatter in the skill/agent file
• "Missing description field": Add description to YAML frontmatter
• "No trigger patterns found": Update description to include clear trigger phrases

Phase 3: GENERATE -- Create Routing Table Entries

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

1. Load routing format specification 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

• "Unknown routing table target": Update routing table mapping logic
• "High-severity conflict": Review conflicting patterns manually before proceeding

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

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

commands/.do.md.backup.{timestamp}

• New entries being added (prefixed with +)
• Modified entries being updated (old with -, new with +)
• Manual entries being preserved (unchanged)

• If diff looks correct: confirm to apply
• If diff shows unexpected changes: abort and investigate
• If using --auto-commit: confirmation is skipped

• Pipe alignment in all tables
• Header separator rows present
• Consistent column counts per table
• No orphaned rows

Phase 4B: UPDATE -- Update Command Files

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

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

Phase 5: VERIFY -- Validate Routing Correctness

python3 ~/.claude/skills/routing-table-updater/scripts/validate.py --target $HOME/claude-code-toolkit/commands/do.md

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

• "Duplicate pattern detected": Remove duplicate from do.md
• "Missing skill/agent file": Remove routing entry or create missing capability
• "Invalid complexity level": Fix complexity value in routing entry

Examples

Example 1: New Skill Created

skills/api-integration-helper/SKILL.md

---
name: api-integration-helper
description: Test API integrations with mock responses and validation. Use when "test API", "API integration", or "mock API".
version: 1.0.0
---

1. SCAN: Detect new file in skills/ directory
2. EXTRACT: Parse frontmatter, extract trigger patterns ["test API", "API integration", "mock API"], complexity Medium
3. GENERATE: Create entry for Intent Detection Patterns table
4. UPDATE: Backup do.md, insert entry alphabetically, validate markdown
5. VERIFY: Run validate.py, confirm no conflicts, all tables intact

| "test API", "API integration", "mock API" | api-integration-helper skill | Medium | [AUTO-GENERATED]

Example 2: Agent Description Updated

1. SCAN: Find modified agents/golang-general-engineer.md
2. EXTRACT: Parse updated domain keywords ["Go", "Golang", "gofmt", "Go concurrency"]
3. GENERATE: Update Domain-Specific routing entry with new keywords
4. UPDATE: Backup, replace existing auto-generated entry, preserve manual entries
5. VERIFY: Confirm no new conflicts, all references valid

-| Go, Golang, gofmt | golang-general-engineer | Medium-Complex | [AUTO-GENERATED]
+| Go, Golang, gofmt, Go concurrency | golang-general-engineer | Medium-Complex | [AUTO-GENERATED]

Example 3: Conflict Detection

1. GENERATE phase detects overlap between api-testing-skill and integration-testing-skill
2. Conflict logged with severity assessment (low: both routes reasonable)
3. Resolution: longer pattern "test API integration" takes precedence for integration skill
4. Document conflict in output, apply specificity rule

| "test API integration" | integration-testing-skill | Medium | [AUTO-GENERATED]
| "test API" | api-testing-skill | Medium | [AUTO-GENERATED]

Example 4: Manual Entry Preserved

| "review Python", "Python quality" | python-general-engineer + python-quality-gate | Medium |

[AUTO-GENERATED]

Batch Mode

pipeline-scaffolder

Batch Input

{
  "domain": "prometheus",
  "agent": { "name": "prometheus-grafana-engineer", "is_new": false },
  "skills": [
    { "name": "prometheus-metrics", "triggers": ["prometheus metrics", "PromQL", "recording rules"], "agent": "prometheus-grafana-engineer" },
    { "name": "prometheus-alerting", "triggers": ["prometheus alerting", "alert rules", "alertmanager"], "agent": "prometheus-grafana-engineer" },
    { "name": "prometheus-operations", "triggers": ["prometheus operations", "prometheus troubleshooting"], "agent": "prometheus-grafana-engineer" }
  ]
}

Batch Process

1. SCAN: Skip full repo scan — use the provided component list directly
2. EXTRACT: Read YAML frontmatter from each listed skill file (verify they exist)
3. GENERATE: Create routing entries for ALL N skills in one pass. Check for inter-batch conflicts (skills within the same batch that share triggers).
4. UPDATE:
   • Add all N routing entries to

     skills/do/references/routing-tables.md

     in one write
   • If agent is new (

     is_new: true

     ), add to

     agents/INDEX.json

   • Update

     skills/do/SKILL.md

     if force-route triggers are needed
   • Create

     commands/{domain}-pipeline.md

     manifest
5. VERIFY: Validate all N entries are present and correctly formatted

Batch vs Single Mode

Integration

• After skill-creator-engineer: New skill created, routing tables need updated entry
• After agent-creator-engineer: New agent created, domain routing needs expansion
• 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)

skill: routing-table-updater

skills/do/SKILL.md

skills/do/references/routing-tables.md

agents/INDEX.json

commands/*.md

Error Handling

Error: "YAML Parse Error in {file}"

Error: "Routing Conflict -- High Severity"

references/conflict-resolution.md

Error: "Manual Entry Overwrite Detected"

Error: "Markdown Table Validation Failed"

Anti-Patterns

Anti-Pattern 1: Fixing Without Backup

Anti-Pattern 2: Skipping Phase Gates

Anti-Pattern 3: Ignoring Conflict Warnings

Anti-Pattern 4: Overwriting Manual Entries

[AUTO-GENERATED]

References

• Anti-Rationalization - Prevents shortcut rationalizations
• Verification Checklist - Pre-completion checks
• Gate Enforcement - Phase transition rules

Domain-Specific Anti-Rationalization

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)