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
| Shape |
Naming |
Answers |
Examples |
| Domain expertise |
<domain>-expert |
"How does X work, and what is good practice?" |
postgresql-expert, react-expert |
| Procedure |
<activity>-workflow |
"What do I do, in what order?" |
tdd-workflow, debugging-workflow |
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
| Category |
Holds |
Reach for it when |
workflows/ |
Procedures: TDD, refactoring, debugging, code review |
The question is "how do I proceed?" |
languages/ |
23 programming languages |
Idiom, tooling, or language-specific behaviour |
frameworks/ |
15 web, mobile and desktop frameworks |
Framework conventions and lifecycle |
api/ |
REST, GraphQL, gRPC, OpenAPI, microservices |
Designing or consuming an interface |
data/ |
Databases, warehouses, pipelines, BI |
Storage, queries, analytics, streaming |
devops/ |
Containers, orchestration, IaC, CI/CD, observability |
Build, deploy, run |
cloud/ |
AWS, Azure, GCP, Cloudflare |
Provider-specific services |
ai/ |
ML, LLM engineering, RAG, agents |
Anything model-based |
security/ |
AppSec, identity, secrets, supply chain, compliance |
A security question, at any stage |
qa/ |
Test frameworks, load, chaos |
Writing or running tests |
tools/ |
Git, documents, browsers, chat platforms, this skill |
Working with a tool rather than a domain |
domains/ |
Industry verticals and enterprise platforms |
Domain rules: healthcare, finance, SAP |
professional/ |
Accounting, legal, banking, FinOps, standards |
Non-engineering expertise |
scientific/ |
Research, quantum, biology |
Scientific computing |
design/ |
Architecture patterns, accessibility |
Structure or interface quality |
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:
| If the task is… |
Use |
Not |
| Driving a browser to test your own app |
playwright-expert |
browser-automation-expert |
| Driving a browser to get data from a site |
browser-automation-expert |
playwright-expert |
| The process of reviewing a change |
code-review-workflow |
code-review-expert |
| What good code looks like per dimension |
code-review-expert |
code-review-workflow |
| A security breach investigation |
incident-response-expert |
debugging-workflow |
| A production defect, no attacker |
debugging-workflow |
incident-response-expert |
| Transactional workload, rows |
postgresql-expert, mysql-expert |
analytical-databases-expert |
| Aggregates over huge tables |
analytical-databases-expert |
postgresql-expert |
| Moving events continuously |
stream-processing-expert |
airflow-expert |
| Scheduled batch orchestration |
airflow-expert |
stream-processing-expert |
| Prompt design and model output |
llm-engineering-expert |
agent-engineering-expert |
| A model that calls tools |
agent-engineering-expert |
llm-engineering-expert |
| Answering over your documents |
rag-expert |
elasticsearch-expert |
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:
- Search the catalogue by tag, not by the name you expected.
- 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.
- 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
1---
2name: skill-router
3version: 1.0.0
4description: >-
5 Find the right skill in the PCL standard library and compose several when a task spans
6 domains. Use when the user asks which skill applies, cannot find a capability, wants to
7 know what the library covers, is starting a task that spans several domains, or when the
8 task involves choosing between overlapping skills, discovering skills by keyword, or
9 deciding whether a new skill is needed.
10category: tools
11tags: [discovery, routing, skill-selection, composition, catalog, meta]
12allowed-tools:
13 - Read
14 - Grep
15 - Glob
16 - Bash(python:*, jq:*)
17metadata:
18 source: https://skillmd.com/skills/personamanagmentlayer/skill-router
19 author: PCL Standard Library
20 complexity: beginner
21---
22
23# Skill Router
24
25The library holds 191 skills across 15 categories. This skill answers which ones
26apply to a task, and how to combine them.
27
28## Core Concepts
29
30### Route on the Task, Not the Technology
31
32"Fix this slow query" is not a PostgreSQL question until you know the query is
33in PostgreSQL. Start from what the user is trying to do, then narrow by the
34technology actually in the repository.
35
36### Two Shapes of Skill
37
38| Shape | Naming | Answers | Examples |
39| -------------------- | --------------------- | --------------------------------------------- | ------------------------------------ |
40| **Domain expertise** | `<domain>-expert` | "How does X work, and what is good practice?" | `postgresql-expert`, `react-expert` |
41| **Procedure** | `<activity>-workflow` | "What do I do, in what order?" | `tdd-workflow`, `debugging-workflow` |
42
43A task usually needs one of each: the workflow drives the sequence, the expert
44supplies the judgement inside it.
45
46### Compose, Don't Concatenate
47
48Loading five skills fills the context and dilutes attention. Load the workflow
49plus the one or two experts whose material the task actually touches, and consult
50a third only if the work reaches it.
51
52## Finding a Skill
53
54The catalogue is machine-readable and is the fastest route:
55
56```bash
57# By keyword across names, descriptions and tags
58jq -r '.skills[] | select(
59 (.name + " " + .description + " " + (.tags | join(" ")))
60 | ascii_downcase | contains("kafka")
61 ) | "\(.category)/\(.name)"' stdlib/catalog/skill-catalog.json
62
63# Everything in a category
64jq -r '.skills[] | select(.category == "security") | .name' stdlib/catalog/skill-index.json
65
66# What a skill covers, before loading it
67jq -r '.skills[] | select(.name == "rag-expert") | .description' stdlib/catalog/skill-catalog.json
68```
69
70Or by filesystem, which is often quicker for a name you half-remember:
71
72```bash
73find stdlib -maxdepth 2 -type d -name '*postgres*'
74grep -rl "watermark" stdlib --include=SKILL.md
75```
76
77Every description contains an explicit `Use when …` clause naming the keywords
78and tasks that should select it. Read that clause rather than guessing from the
79name.
80
81## The Category Map
82
83| Category | Holds | Reach for it when |
84| --------------- | ---------------------------------------------------- | ---------------------------------------------- |
85| `workflows/` | Procedures: TDD, refactoring, debugging, code review | The question is "how do I proceed?" |
86| `languages/` | 23 programming languages | Idiom, tooling, or language-specific behaviour |
87| `frameworks/` | 15 web, mobile and desktop frameworks | Framework conventions and lifecycle |
88| `api/` | REST, GraphQL, gRPC, OpenAPI, microservices | Designing or consuming an interface |
89| `data/` | Databases, warehouses, pipelines, BI | Storage, queries, analytics, streaming |
90| `devops/` | Containers, orchestration, IaC, CI/CD, observability | Build, deploy, run |
91| `cloud/` | AWS, Azure, GCP, Cloudflare | Provider-specific services |
92| `ai/` | ML, LLM engineering, RAG, agents | Anything model-based |
93| `security/` | AppSec, identity, secrets, supply chain, compliance | A security question, at any stage |
94| `qa/` | Test frameworks, load, chaos | Writing or running tests |
95| `tools/` | Git, documents, browsers, chat platforms, this skill | Working with a tool rather than a domain |
96| `domains/` | Industry verticals and enterprise platforms | Domain rules: healthcare, finance, SAP |
97| `professional/` | Accounting, legal, banking, FinOps, standards | Non-engineering expertise |
98| `scientific/` | Research, quantum, biology | Scientific computing |
99| `design/` | Architecture patterns, accessibility | Structure or interface quality |
100
101Note that `design/design-expert` covers **software architecture**, not visual
102design — a legacy naming artefact. `accessibility-expert` is the interface skill.
103
104## Choosing Between Overlapping Skills
105
106Several pairs look similar. The distinctions that matter:
107
108| If the task is… | Use | Not |
109| ------------------------------------------- | ----------------------------------- | ----------------------------- |
110| Driving a browser to _test your own app_ | `playwright-expert` | `browser-automation-expert` |
111| Driving a browser to _get data from a site_ | `browser-automation-expert` | `playwright-expert` |
112| The _process_ of reviewing a change | `code-review-workflow` | `code-review-expert` |
113| _What good code looks like_ per dimension | `code-review-expert` | `code-review-workflow` |
114| A security breach investigation | `incident-response-expert` | `debugging-workflow` |
115| A production defect, no attacker | `debugging-workflow` | `incident-response-expert` |
116| Transactional workload, rows | `postgresql-expert`, `mysql-expert` | `analytical-databases-expert` |
117| Aggregates over huge tables | `analytical-databases-expert` | `postgresql-expert` |
118| Moving events continuously | `stream-processing-expert` | `airflow-expert` |
119| Scheduled batch orchestration | `airflow-expert` | `stream-processing-expert` |
120| Prompt design and model output | `llm-engineering-expert` | `agent-engineering-expert` |
121| A model that _calls tools_ | `agent-engineering-expert` | `llm-engineering-expert` |
122| Answering over your documents | `rag-expert` | `elasticsearch-expert` |
123
124## Composition Patterns
125
126Common tasks and the skills that serve them:
127
128**"Add a feature to our API, test-first"**
129`tdd-workflow` (the loop) → `api-design-expert` (contract) → the language skill →
130`code-review-workflow` (before merge)
131
132**"Our checkout is slow"**
133`debugging-workflow` (method) → `performance-expert` (measurement) → the database
134or framework skill, once measurement says which
135
136**"Build an assistant over our documentation"**
137`rag-expert` (retrieval) → `llm-engineering-expert` (generation and evaluation) →
138`agent-engineering-expert` (only if it calls tools) → `identity-access-expert`
139(who may see which documents)
140
141**"Harden our release pipeline"**
142`supply-chain-security-expert` (provenance, SBOM) → `cicd-expert` (pipeline) →
143`secrets-management-expert` (credentials)
144
145**"Make the dashboard accessible"**
146`accessibility-expert` (conformance) → the framework skill (implementation) →
147`qa-expert` (regression coverage)
148
149**"Migrate a large table with no downtime"**
150`refactoring-workflow` (parallel change) → the database skill (mechanics) →
151`sre-expert` (rollout and rollback)
152
153## When No Skill Fits
154
155Before concluding a skill is missing:
156
1571. **Search the catalogue by tag**, not by the name you expected.
1582. **Check `references/`** — the topic may be a section inside a broader skill.
159 `rails` lives in `ruby-expert`, `spark` in `databricks-expert` and
160 `analytical-databases-expert`.
1613. **Check whether a broader skill covers it.** `vector-databases` is inside
162 `rag-expert` by design, because the choice only matters in that context.
163
164If it is genuinely absent, the test for adding one is whether it is a distinct
165_decision context_ rather than a distinct technology. Five vector stores share
166one mental model and belong in one skill with per-store references; MySQL and
167PostgreSQL differ enough in design consequences to warrant separate skills.
168
169Use `skill-creator-expert` to author it, and `scripts/validate-skills.py` to
170check conformance.
171
172## Best Practices
173
174- **Read the `Use when` clause** before loading a skill; it is written to be the
175 routing signal.
176- **Start with the workflow** when the question is procedural — it will name the
177 expert skills it needs.
178- **Load two or three skills, not six.** Add a fourth when the work reaches it.
179- **Prefer the specific skill.** `mysql-expert` over `sql-expert` when the
180 database is MySQL.
181- **Consult `security/` early**, not as a final review — the cheapest security
182 fixes are design decisions.
183- **Follow the reference links** rather than loading a second skill for a detail;
184 `references/` is where the depth lives.
185
186## Anti-Patterns
187
188- **Routing on a keyword in isolation.** "Java" in "JavaScript" is not
189 `java-expert`.
190- **Loading every plausibly related skill** — dilutes attention and fills the
191 context budget.
192- **Picking the general skill** when a specific one exists.
193- **Skipping the workflow skill** and improvising the procedure.
194- **Assuming a topic is missing** because the skill is not named after it.
195
196## Resources
197
198- `stdlib/catalog/skill-index.json` — name, category, path, tags
199- `stdlib/catalog/skill-catalog.json` — full descriptions, sizes, reference lists
200- `stdlib/SKILLS_INVENTORY.md` — human-readable listing by category
201- `stdlib/CHANGELOG.md` — versioning and migration notes
202- `skill-creator-expert` — authoring a new skill