Domain Expert Router
What this does
This repo (domain-experts) is a growing library of job-role SKILL.md files, each written so an agent can adopt that role's actual reasoning process — not a job-description summary. This skill is the dispatcher: given a user's request for a specific role/expert judgment, find the best-matching role in the library and load it, or say honestly that it's not covered yet.
Coverage is a small fraction of the ~1,016 O*NET occupations tracked in ROADMAP.md (see its **Progress:** line for the current count — check it rather than assuming a number, since this file isn't auto-regenerated) — a no-match result is the common case, not an edge case. Handle it as a first-class outcome, not an afterthought.
Procedure
Identify the role being asked for, in plain terms, from the user's request (e.g. "review this contract like a lawyer" → role: contracts lawyer).
Find the best match. Run:
npx domain-experts match "<the role/task in plain language>" --json
(or, if the CLI isn't available, grep roles/*/SKILL.md frontmatter description fields for the closest fit — same idea, no tooling required.)
If confident: true:
- Read the matched file in full (
best.file from the JSON, or the path the CLI printed).
- Adopt its reasoning process for the rest of this task: follow its "Decision framework," reflect its "Mental models & heuristics," and match its "Communication style" section.
- Mention which role file you loaded, briefly (one line), so the user knows the source — don't silently role-play without attribution.
- If the role's frontmatter has
maturity: draft, treat its content as solid but not yet practitioner-verified — still use it, no need to caveat every sentence, but don't claim it's been reviewed by a real practitioner if asked.
If confident: false (no strong match) — this is a hybrid response, not a dead end:
- State the gap honestly first: "No role for
<X> in the repo yet." If the match command returned low-confidence candidates, mention them as the closest available, but don't pretend they're a real fit if they aren't.
- Point at how to close the gap: check
ROADMAP.md for the closest O*NET occupation code (if one exists) and mention that a PR following TEMPLATE.md/CONTRIBUTING.md would add it.
- Then offer to proceed anyway: ask, or if the user's intent is clearly "just answer me now," proceed to reason as that expert using general knowledge — but flag it clearly and specifically, e.g. "Improvising this from general knowledge, not from a reviewed repo role — treat with more skepticism than a drafted role." Do not present improvised reasoning with the same confidence framing as a loaded
SKILL.md.
- Never silently fall back to generic reasoning while implying it came from a vetted role file.
Why the honest-gap step matters
The whole point of this repo is that a loaded SKILL.md encodes actually-considered first-principles reasoning, not off-the-cuff generalist output. Silently improvising and presenting it with the same weight defeats that purpose and erodes trust in the roles that are drafted. Saying "this isn't covered yet" costs nothing and is more useful than a confident-sounding guess mislabeled as expert judgment.
Example
User: "Review this vendor contract like our in-house counsel would."
- Role identified: contracts/commercial lawyer.
npx domain-experts match "in-house counsel contract review" --json → confident match: lawyer-contracts.- Read
roles/lawyer-contracts/SKILL.md in full, adopt its worst-case-first reading heuristic, its risk-allocation decision framework, its US-commercial-law scope note.
- Respond: "Using this repo's
lawyer-contracts role (scoped to US general commercial law) — here's the review: ..."
User: "What would a wildlife veterinarian say about this animal's symptoms?"
- Role identified: wildlife veterinarian — not in
roles/.
- Match returns no confident hit.
- Respond: "No wildlife-veterinarian role in the repo yet (closest tracked-but-undrafted O*NET occupation would be
29-1131.00 Veterinarians — check ROADMAP.md). Want me to reason through this from general knowledge anyway? I'd flag that answer as unreviewed/improvised, not sourced from a vetted role."
1---2name: domain-expert-router3description: Use whenever the user asks you to act as, consult, or reason like a specific job role/domain expert (e.g. "review this like a CFO," "what would a UX designer say," "act as a contracts lawyer") and this repo's roles/ directory is available. Finds the best-matching role SKILL.md and adopts it, or honestly reports the gap if none exists.4---56# Domain Expert Router78## What this does910This repo (`domain-experts`) is a growing library of job-role `SKILL.md` files, each written so an agent can adopt that role's actual reasoning process — not a job-description summary. This skill is the dispatcher: given a user's request for a specific role/expert judgment, find the best-matching role in the library and load it, or say honestly that it's not covered yet.1112Coverage is a small fraction of the ~1,016 O*NET occupations tracked in `ROADMAP.md` (see its `**Progress:**` line for the current count — check it rather than assuming a number, since this file isn't auto-regenerated) — a no-match result is the common case, not an edge case. Handle it as a first-class outcome, not an afterthought.1314## Procedure15161. **Identify the role being asked for**, in plain terms, from the user's request (e.g. "review this contract like a lawyer" → role: contracts lawyer).17182. **Find the best match.** Run:19 ```sh20 npx domain-experts match "<the role/task in plain language>" --json21 ```22 (or, if the CLI isn't available, grep `roles/*/SKILL.md` frontmatter `description` fields for the closest fit — same idea, no tooling required.)23243. **If `confident: true`:**25 - Read the matched file in full (`best.file` from the JSON, or the path the CLI printed).26 - Adopt its reasoning process for the rest of this task: follow its "Decision framework," reflect its "Mental models & heuristics," and match its "Communication style" section.27 - Mention which role file you loaded, briefly (one line), so the user knows the source — don't silently role-play without attribution.28 - If the role's frontmatter has `maturity: draft`, treat its content as solid but not yet practitioner-verified — still use it, no need to caveat every sentence, but don't claim it's been reviewed by a real practitioner if asked.29304. **If `confident: false` (no strong match) — this is a hybrid response, not a dead end:**31 - **State the gap honestly first:** "No role for `<X>` in the repo yet." If the match command returned low-confidence candidates, mention them as the closest available, but don't pretend they're a real fit if they aren't.32 - **Point at how to close the gap:** check `ROADMAP.md` for the closest O*NET occupation code (if one exists) and mention that a PR following `TEMPLATE.md`/`CONTRIBUTING.md` would add it.33 - **Then offer to proceed anyway:** ask, or if the user's intent is clearly "just answer me now," proceed to reason as that expert using general knowledge — but flag it clearly and specifically, e.g. "Improvising this from general knowledge, not from a reviewed repo role — treat with more skepticism than a drafted role." Do not present improvised reasoning with the same confidence framing as a loaded `SKILL.md`.34 - Never silently fall back to generic reasoning while implying it came from a vetted role file.3536## Why the honest-gap step matters3738The whole point of this repo is that a loaded `SKILL.md` encodes actually-considered first-principles reasoning, not off-the-cuff generalist output. Silently improvising and presenting it with the same weight defeats that purpose and erodes trust in the roles that *are* drafted. Saying "this isn't covered yet" costs nothing and is more useful than a confident-sounding guess mislabeled as expert judgment.3940## Example4142> User: "Review this vendor contract like our in-house counsel would."43441. Role identified: contracts/commercial lawyer.452. `npx domain-experts match "in-house counsel contract review" --json` → confident match: `lawyer-contracts`.463. Read `roles/lawyer-contracts/SKILL.md` in full, adopt its worst-case-first reading heuristic, its risk-allocation decision framework, its US-commercial-law scope note.474. Respond: "Using this repo's `lawyer-contracts` role (scoped to US general commercial law) — here's the review: ..."4849> User: "What would a wildlife veterinarian say about this animal's symptoms?"50511. Role identified: wildlife veterinarian — not in `roles/`.522. Match returns no confident hit.533. Respond: "No wildlife-veterinarian role in the repo yet (closest tracked-but-undrafted O*NET occupation would be `29-1131.00` Veterinarians — check `ROADMAP.md`). Want me to reason through this from general knowledge anyway? I'd flag that answer as unreviewed/improvised, not sourced from a vetted role."
wonsukchoi