Routing, Experts & Skills
Roles, topics, experts, and skills solve different configuration problems:
| Concept | Purpose |
|---|---|
| Role | Responsibility, prompt, and available tool containers |
| Topic | Model binding for a type of work |
| Expert | Additional prompt guidance, deliverable expectations, skills, and optional model preference |
| Skill | Domain instructions loaded into model context |
| Persona | User-facing identity and tone |
Root and specialists
Section titled “Root and specialists”The root runs as general, answers with its own tools, and may delegate through
spawn_child. Classification provides context hints rather than a mandatory
routing hop. Specialist roles include coding, research, architecture, review,
QA, communication, design, DevOps, security, data, AI, finance, automation,
project management, and writing.
Use GET /api/roles and GET /api/tools/role-map to inspect the current role
bindings. Tool access is separate from permission to execute an action.
Model resolution
Section titled “Model resolution”For a planned child, a configured lane executor takes precedence. Otherwise an expert’s explicit model preference precedes the topic primary. A missing specialist binding fails with a configuration error. The root alone can select the configured default. Backup bindings apply to failure recovery rather than as a proactive cheaper tier; worker paths have their own fallback behavior.
Configure topics through GET /api/topics, PUT /api/topics/:topic/binding,
and PATCH /api/topics/:topic/config. Text topics usually match role names;
embedding, OCR, vision, and voice have separate capability requirements.
Assigning the same model to every text topic is supported through
POST /api/topics/assign-all with a registered model name. It does not create
embedding or vision capabilities in a text-only model.
Experts and skills
Section titled “Experts and skills”Select an expert with /expert or the expert controls in your client. The worker
receives the expert’s role tools and prompt guidance. Critical rules and success
metrics are prompt instructions, not enforced output schemas or independent
verification of the result.
System skills are database-backed; filesystem SKILL.md documents are discovered
from configured directories. Skill distillation creates proposals for review;
a proposal is not automatically a trusted new capability.
Model examples and role suggestions are starting points. Verify tool calling, output quality, and cost using the models and tasks you actually configure.