---
name: ellmos-ai/semantic-persona-routing
source: https://app.decimal.ai/s/ellmos-ai-semantic-persona-routing@2/SKILL.md
source_sha256: 3c5cdb071afd
---
# Semantic Persona Routing
Route by capability first and apply personality second. Build a portable map that
keeps semantic role choice, deterministic endpoint lookup and provider-specific
loading separate.
## Routing model
```text
request
-> semantic domain/coordinator role
-> expert capability
-> explicit or live-resolved skill endpoint
-> optional persona overlay
-> provider adapter loads and executes
```
A persona controls communication style, priorities and interaction patterns. It
does not grant tools, permissions or subject-matter capability. A role coordinates;
an expert narrows the domain; a skill is the executable endpoint.
## Build the routing map
Use explicit metadata as authority and lexical similarity only as a candidate:
```bash
python scripts/build_routing_map.py \
--roles-dir path/to/roles \
--personas-dir path/to/personas \
--skills-dir path/to/skills \
--out routing-map.json
```
The builder understands common `SKILL.md` fields such as `type`,
`orchestrates.experts`, `parent_agents`, `skills`, descriptions and provenance.
It produces a runtime map without requiring the source system to be installed.
Read [routing-map-schema.md](references/routing-map-schema.md) before extending the
format.
Each exported skill ID is unique. When multiple source files declare the same
stable ID, the builder selects the lexicographically first relative source path
deterministically and records a `duplicate-skill-id` issue; it never emits two
skill entries with the same ID. Declared expert and persona skill references are
normalized to a clean ID only when that ID exists in the exported registry.
Malformed, unknown, and normalized references stay visible in `issues`; unknown
or invalid references never become endpoints or persona compatibility links.
Do not automatically promote `candidate_skills`. Confirm them against a live skill
resolver or source metadata first.
## Route a request
### 1. Select the coordinator role semantically
Compare the request with role names, descriptions and use cases. Prefer the
narrowest role that can coordinate the whole request. Keep multiple candidates
visible when confidence is low; ask the user only when the choice materially
changes the result.
### 2. Select an expert within the role
Use only experts connected to the chosen coordinator unless the request clearly
spans roles. A direct expert request may skip the coordinator for execution, but
retain the coordinator link in the route explanation.
### 3. Resolve executable endpoints
Resolve in this order:
1. `endpoint_skills` from explicit source metadata or exact provenance;
2. a current external skill resolver or local skill finder;
3. verified `candidate_skills`;
4. visible `GAP` when no endpoint exists.
Never route to an expert name as though it were an installed skill. A missing
endpoint is a porting gap, not permission to fabricate one.
Read [endpoint-resolution.md](references/endpoint-resolution.md) when connecting a
live registry, lexical finder or provider-specific skill loader.
### 4. Apply the persona overlay
Choose a persona attached to the selected role or expert. If several personas fit,
prefer one whose declared limits and style match the task. Apply no persona when
none is explicitly connected.
Persona instructions cannot override safety rules, locks, user decisions,
professional boundaries or tool permissions.
### 5. Load and execute
Use the provider's native skill/agent loading mechanism. Load the selected live
skill instructions before execution. Keep the router lean; execution belongs to
the worker or current agent with the resolved skills loaded.
## Route receipt
Return or record:
```text
ROLE:
EXPERT:
SKILLS:
PERSONA:
RESOLUTION: explicit | provenance | live-resolver | verified-candidate | GAP
CONFIDENCE: high | medium | low
WHY:
GAPS:
```
Rebuild the map when source roles or skill inventory change. A live resolver may
supersede a stale map for endpoint availability, but it must not silently rewrite
the semantic role taxonomy.
## Example
Request: "Organize my receipts and prepare the tax-year overview."
The router selects an office coordinator, then the tax expert, resolves the
installed tax skill, and finally applies an explicitly linked meticulous tax
persona. If the tax expert exists but no portable tax skill is installed, report
`GAP` and continue only through an explicitly configured fallback.
## Changelog
### 1.0.0 (2026-07-28)
- Extracted the provider-neutral role/expert/skill chain from a proven domain
router pattern and added portable map generation with visible endpoint gaps.