Skill Router

Skill Router

The library holds 191 skills across 15 categories. This skill answers which ones apply to a task, and how to combine them.

Core Concepts

Route on the Task, Not the Technology

"Fix this slow query" is not a PostgreSQL question until you know the query is in PostgreSQL. Start from what the user is trying to do, then narrow by the technology actually in the repository.

Two Shapes of Skill

A task usually needs one of each: the workflow drives the sequence, the expert supplies the judgement inside it.

Compose, Don't Concatenate

Loading five skills fills the context and dilutes attention. Load the workflow plus the one or two experts whose material the task actually touches, and consult a third only if the work reaches it.

Finding a Skill

The catalogue is machine-readable and is the fastest route:

# By keyword across names, descriptions and tags
jq -r '.skills[] | select(
         (.name + " " + .description + " " + (.tags | join(" ")))
         | ascii_downcase | contains("kafka")
       ) | "\(.category)/\(.name)"' stdlib/catalog/skill-catalog.json

# Everything in a category
jq -r '.skills[] | select(.category == "security") | .name' stdlib/catalog/skill-index.json

# What a skill covers, before loading it
jq -r '.skills[] | select(.name == "rag-expert") | .description' stdlib/catalog/skill-catalog.json

Or by filesystem, which is often quicker for a name you half-remember:

find stdlib -maxdepth 2 -type d -name '*postgres*'
grep -rl "watermark" stdlib --include=SKILL.md

Every description contains an explicit Use when … clause naming the keywords and tasks that should select it. Read that clause rather than guessing from the name.

The Category Map

Note that design/design-expert covers software architecture, not visual design — a legacy naming artefact. accessibility-expert is the interface skill.

Choosing Between Overlapping Skills

Several pairs look similar. The distinctions that matter:

Composition Patterns

Common tasks and the skills that serve them:

"Add a feature to our API, test-first" tdd-workflow (the loop) → api-design-expert (contract) → the language skill → code-review-workflow (before merge)

"Our checkout is slow" debugging-workflow (method) → performance-expert (measurement) → the database or framework skill, once measurement says which

"Build an assistant over our documentation" rag-expert (retrieval) → llm-engineering-expert (generation and evaluation) → agent-engineering-expert (only if it calls tools) → identity-access-expert (who may see which documents)

"Harden our release pipeline" supply-chain-security-expert (provenance, SBOM) → cicd-expert (pipeline) → secrets-management-expert (credentials)

"Make the dashboard accessible" accessibility-expert (conformance) → the framework skill (implementation) → qa-expert (regression coverage)

"Migrate a large table with no downtime" refactoring-workflow (parallel change) → the database skill (mechanics) → sre-expert (rollout and rollback)

When No Skill Fits

Before concluding a skill is missing:

1. Search the catalogue by tag, not by the name you expected.
2. Check references/ — the topic may be a section inside a broader skill. rails lives in ruby-expert, spark in databricks-expert and analytical-databases-expert.
3. Check whether a broader skill covers it. vector-databases is inside rag-expert by design, because the choice only matters in that context.

If it is genuinely absent, the test for adding one is whether it is a distinct decision context rather than a distinct technology. Five vector stores share one mental model and belong in one skill with per-store references; MySQL and PostgreSQL differ enough in design consequences to warrant separate skills.

Use skill-creator-expert to author it, and scripts/validate-skills.py to check conformance.

Best Practices

• Read the Use when clause before loading a skill; it is written to be the routing signal.
• Start with the workflow when the question is procedural — it will name the expert skills it needs.
• Load two or three skills, not six. Add a fourth when the work reaches it.
• Prefer the specific skill. mysql-expert over sql-expert when the database is MySQL.
• Consult security/ early, not as a final review — the cheapest security fixes are design decisions.
• Follow the reference links rather than loading a second skill for a detail; references/ is where the depth lives.

Anti-Patterns

• Routing on a keyword in isolation. "Java" in "JavaScript" is not java-expert.
• Loading every plausibly related skill — dilutes attention and fills the context budget.
• Picking the general skill when a specific one exists.
• Skipping the workflow skill and improvising the procedure.
• Assuming a topic is missing because the skill is not named after it.

Resources

• stdlib/catalog/skill-index.json — name, category, path, tags
• stdlib/catalog/skill-catalog.json — full descriptions, sizes, reference lists
• stdlib/SKILLS_INVENTORY.md — human-readable listing by category
• stdlib/CHANGELOG.md — versioning and migration notes
• skill-creator-expert — authoring a new skill