Skip to content

notque/vexjoy-agent / skills/meta/toolkit

toolkit

Verified

Toolkit management: create and evaluate skills and agents, manage routing tables, generate Claude.md.

FileKindSize
SKILL.mdskill md15.5 KB
agents/skill-creator/analyzer.mdmarkdown4.8 KB
agents/skill-creator/comparator.mdmarkdown4.7 KB
agents/skill-creator/grader.mdmarkdown3.9 KB
assets/skill-creator/eval_viewer.htmlother57.1 KB
references/agent-comparison.mdmarkdown11.5 KB
references/agent-comparison/benchmark-tasks.mdmarkdown6.8 KB
references/agent-comparison/do-creation-compliance-tasks.jsonconfig8.5 KB
references/agent-comparison/examples-and-errors.mdmarkdown1.0 KB
references/agent-comparison/grading-rubric.mdmarkdown4.3 KB
references/agent-comparison/methodology.mdmarkdown7.4 KB
references/agent-comparison/optimization-guide.mdmarkdown12.0 KB
references/agent-comparison/optimization-tasks.example.jsonconfig853 B
references/agent-comparison/optimize-phase.mdmarkdown9.3 KB
references/agent-comparison/read-only-ops-short-tasks.jsonconfig375 B
references/agent-comparison/report-template.mdmarkdown3.8 KB
references/agent-comparison/socratic-debugging-body-short-tasks.jsonconfig372 B
references/agent-comparison/socratic-debugging-trigger-tasks.jsonconfig2.8 KB
references/agent-creator.mdmarkdown10.9 KB
references/agent-creator/agent-design-patterns.mdmarkdown12.4 KB
references/agent-creator/agent-eval-design.mdmarkdown7.7 KB
references/agent-creator/agent-frontmatter-template.mdmarkdown9.3 KB
references/agent-evaluation.mdmarkdown10.6 KB
references/agent-evaluation/batch-evaluation.mdmarkdown1.6 KB
references/agent-evaluation/common-issues.mdmarkdown2.1 KB
references/agent-evaluation/report-templates.mdmarkdown2.2 KB
references/agent-evaluation/scoring-rubric.mdmarkdown2.4 KB
references/blind-ab-tests.mdmarkdown7.8 KB
references/generate-claudemd.mdmarkdown11.0 KB
references/generate-claudemd/CLAUDEMD_TEMPLATE.mdmarkdown4.1 KB
references/generate-claudemd/examples-and-errors.mdmarkdown7.4 KB
references/github-profile-rules.mdmarkdown7.5 KB
references/github-profile-rules/github-api-patterns.mdmarkdown8.2 KB
references/github-profile-rules/rule-categories.mdmarkdown4.8 KB
references/hook-development.mdmarkdown10.9 KB
references/hook-development/architecture.mdmarkdown3.7 KB
references/hook-development/code-examples.mdmarkdown9.4 KB
references/hook-development/preferred-patterns.mdmarkdown6.5 KB
references/hook-development/telemetry-database.mdmarkdown6.5 KB
references/routing-table-updater.mdmarkdown10.2 KB
references/routing-table-updater/batch-mode.mdmarkdown2.1 KB
references/routing-table-updater/conflict-resolution.mdmarkdown3.8 KB
references/routing-table-updater/error-handling.mdmarkdown1.9 KB
references/routing-table-updater/examples.mdmarkdown4.8 KB
references/routing-table-updater/extraction-patterns.mdmarkdown2.2 KB
references/routing-table-updater/routing-format.mdmarkdown3.6 KB
references/routing-table-updater/skill-examples.mdmarkdown2.7 KB
references/skill-composer.mdmarkdown9.1 KB
references/skill-composer/compatibility-matrix.mdmarkdown13.0 KB
references/skill-composer/composition-patterns.mdmarkdown4.9 KB
references/skill-composer/examples.mdmarkdown17.1 KB
references/skill-composer/skill-patterns.mdmarkdown12.5 KB
references/skill-creator.mdmarkdown28.9 KB
references/skill-creator/agent-template.mdmarkdown18.5 KB
references/skill-creator/artifact-schemas.mdmarkdown8.2 KB
references/skill-creator/bundled-components.mdmarkdown2.3 KB
references/skill-creator/complexity-tiers.mdmarkdown8.0 KB
references/skill-creator/domain-research-targets.mdmarkdown13.2 KB
references/skill-creator/enrichment-workflow.mdmarkdown9.9 KB
references/skill-creator/error-catalog.mdmarkdown9.9 KB
references/skill-creator/preferred-patterns.mdmarkdown11.7 KB
references/skill-creator/progressive-disclosure.mdmarkdown8.5 KB
references/skill-creator/skill-template.mdmarkdown14.6 KB
references/skill-creator/workflow-patterns.mdmarkdown7.6 KB
references/system-upgrade.mdmarkdown11.0 KB
references/system-upgrade/component-audit-checklists.mdmarkdown8.4 KB
references/system-upgrade/upgrade-failure-modes.mdmarkdown8.7 KB
references/system-upgrade/upgrade-signal-parsing.mdmarkdown7.3 KB
references/toolkit-evolution.mdmarkdown14.5 KB
references/toolkit-evolution/diagnose-scripts.mdmarkdown9.5 KB
references/toolkit-evolution/evolution-history.mdmarkdown5.5 KB
references/toolkit-evolution/evolution-report-template.mdmarkdown716 B
references/toolkit-evolution/evolve-preferred-patterns.mdmarkdown6.9 KB
references/toolkit-evolution/evolve-scripts.mdmarkdown3.7 KB
references/toolkit-governance.mdmarkdown16.0 KB
references/toolkit-governance/adr-lifecycle.mdmarkdown10.9 KB
references/toolkit-governance/frontmatter-compliance.mdmarkdown11.1 KB
references/toolkit-governance/hook-standardization.mdmarkdown21.5 KB
references/toolkit-governance/routing-table-patterns.mdmarkdown11.6 KB
references/weak-model-uplift.mdmarkdown10.3 KB
scripts/agent-comparison/compare.pyscript2.3 KB
scripts/agent-comparison/generate_variant.pyscript19.6 KB
scripts/agent-comparison/optimize_loop.pyscript89.3 KB
scripts/agent-comparison/trigger_eval.pyscript19.5 KB
scripts/routing-table-updater/extract_metadata.pyscript10.8 KB
scripts/routing-table-updater/generate_routes.pyscript10.5 KB
scripts/routing-table-updater/scan.pyscript4.7 KB
scripts/routing-table-updater/update_routing.pyscript12.4 KB
scripts/routing-table-updater/validate.pyscript7.3 KB
scripts/skill-composer/build_dag.pyscript12.5 KB
scripts/skill-composer/discover_skills.pyscript12.1 KB
scripts/skill-composer/validate.pyscript12.3 KB
scripts/skill-creator/aggregate_benchmark.pyscript10.0 KB
scripts/skill-creator/eval_compare.pyscript10.2 KB
scripts/skill-creator/optimize_description.pyscript12.5 KB
scripts/skill-creator/package_results.pyscript7.8 KB
scripts/skill-creator/run_eval.pyscript6.3 KB

references/routing-table-updater.md

View on GitHub
# 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**

```bash
python3 ~/.claude/skills/toolkit/scripts/routing-table-updater/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**

```bash
python3 ~/.claude/skills/toolkit/scripts/routing-table-updater/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**

```bash
python3 ~/.claude/skills/toolkit/scripts/routing-table-updater/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 groups

**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, conflicts are documented, and no duplicates remain within the same group. Proceed to Phase 4 only after the gate passes. See `references/error-handling.md` for gate failure recovery.

---

### Phase 4: UPDATE -- Repair INDEX.json

**Goal**: Bring `skills/INDEX.json` and `agents/INDEX.json` in line with filesystem state.

**Constraints**: Both indices are generated, gitignored artifacts — repair means regenerating from frontmatter via the repo scripts; hand-edits to index files are lost on the next regeneration; source SKILL.md and agent files stay untouched; run from the repo root.

**Step 1: Regenerate both indices**

```bash
cd $HOME/vexjoy-agent
python3 scripts/generate-skill-index.py
python3 scripts/generate-agent-index.py
```

**Step 2: Check for phantom entries**

Every entry's `file` path must exist on disk:

```bash
python3 - <<'EOF'
import json, os
for idx, key in (("skills/INDEX.json", "skills"), ("agents/INDEX.json", "agents")):
    entries = json.load(open(idx))[key]
    phantom = [n for n, e in entries.items() if not os.path.exists(e["file"])]
    print(idx, len(entries), "entries,", len(phantom), "phantom", phantom or "")
EOF
```

**Gate**: Both generators exit 0 and both indices contain zero phantom `file` paths. On generator failure, fix the offending frontmatter (the error names the file) and rerun. Proceed to Phase 5 only after the gate passes.

---

### Phase 5: VERIFY -- Validate Routing Correctness

**Goal**: Final validation of the skill package and the rebuilt indices.

**Constraints**: No duplicate trigger phrases within an index; every index entry's `file` path exists; complexity values must match Simple/Medium/Complex; overlapping patterns documented with priority rules.

**Step 1: Run validation script**

```bash
python3 ~/.claude/skills/toolkit/scripts/routing-table-updater/validate.py
```

Validates skill package structure, SKILL.md frontmatter, and script executability. Exit 0 = pass.

**Step 2: Understand verification checks**

1. **Structural**: Skill package complete (SKILL.md, scripts, references), frontmatter parses
2. **Content**: No duplicate triggers, every index entry's `file` path exists (Phase 4 Step 2 check)
3. **Conflicts**: Overlapping patterns documented, priority rules applied

**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: call the Skill tool with `toolkit` and run its Routing Tables mode.

The skill reads metadata from all skills and agents but never modifies them. Its only write targets are the generated indices `skills/INDEX.json` and `agents/INDEX.json`, always via the repo generator scripts.

---

## 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`: routing entry format specification (frontmatter routing block fields, INDEX.json entry shape, regeneration commands)
- `${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
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall