Skip to main content

​
Voice → Skill Catalog operator workflow

Skills-based routing is a three-tier hierarchy: a skill in the tenant catalog, a certification on top of that skill when a queue is regulated, and an assignment of the skill to an agent. The Voice → Skill catalog page (/voice/skill-catalog) governs the first tier — the canonical list of skills the other two tiers reference. Get the catalog right and routing enforces your vocabulary at every write; leave it empty and routing has nothing to enforce against. This guide walks the full operator workflow: the catalog anatomy, recipes that build a skill end-to-end from registration to observing the dispatch match, what happens when an agent’s skills change mid-routing, and the limits of where skills live and who can change them.

​
1. Anatomy of the hierarchy

Three layers, one matching path:
  1. Skill (catalog row) — one row per tag: a slug (spanish), a display label, an optional description, and an active flag. The slug is the matcher key. Archiving a skill takes the slug out of the accepted set without deleting history.
  2. Certification (expiry window) — only for regulated queues. Layers a validity window on a skill an agent already holds; a lapsed certification drops the agent out of queues that require the skill at the next dispatch tick. Never grants a skill — see Skill certifications.
  3. Assignment (agent skill list) — the skills each agent carries, with an optional 1–5 proficiency per skill. The dispatcher intersects the queue’s required skills with the agent’s assignment on every dispatch cycle.
Routing vs groups. Agent groups and teams are a static membership: an agent belongs to the group whether or not the grouping was set deliberately. Skill-based routing matches on capability instead — the dispatcher evaluates skill coverage at dispatch time, so staffing follows what agents are certified and proficient in, not which bucket an admin last dropped them into. Use groups for organizational reporting; use skills for who actually receives the call.

​
2. Recipes, not just definitions

​
Register a skill

  1. Open Voice → Skill catalog.
  2. Click Create skill and fill in the slug, display label, and an optional description.
  3. Submit. The skill is active and assignable immediately — the queue and agent skill pickers only offer registered, active slugs.
The slug is the matcher key queues and agents reference. The dialog normalizes it to lowercase and enforces lowercase ASCII letters, digits, _, - (max 60 characters) with the same rule the API validation applies, so a client-valid slug never round trips to a 422. The slug is immutable once registered — to change it, archive the row and re-register under the corrected slug. The equivalent API call:
A duplicate active slug returns 409 Conflict. The page and the queue/agent pickers read the active list, so registration is immediately visible everywhere.

​
Attach a certification level (regulated queues only)

Only when the queue is regulated (HIPAA, FINRA, insurance producer, licensed counsel):
  1. Open Voice → Skill certifications.
  2. Click Issue certification, pick the agent and the registered slug, set an optional proficiency (1–5) and an expiry date.
  3. A queue that requires the skill only dispatches to agents whose certification is still within its window.
Skip this tier for ordinary queues — an agent with an empty certification map keeps routing on their assignment alone.

​
Assign the skill to an agent

  1. Open the agent’s profile (or Agents → edit in the voice surface).
  2. In the Skills field, pick from the registered slugs — the picker only offers active catalog entries.
  3. Save. The assignment is validated against the catalog at write time; an unregistered slug returns 422 UNKNOWN_SKILL and nothing is persisted.
The API equivalent replaces the full list:
The call replaces the agent’s skill set. An empty array is always valid — it means “any skill,” the wildcard membership.

​
Observe the dispatch match

Routing is observable, not inferred:
  1. Create or update a queue with a required skill (see Voice queues).
  2. Place a call onto that queue while the assigned agent is in the Available state.
  3. On the dispatch tick the matcher intersects the queue’s required skills with the member skill sets; the call bridges to the agent whose skills cover the requirement.
If the call sits until overflow fires, check the tuple match: the queue’s required slug and the agent’s assigned slug must be the same registered slug, character for character.

​
3. What happens when a skill or assignment changes

Changes take effect on evaluation, not enrollment — there is no re-sync step.
  • Edit a catalog row (label/description/active flag) — the next queue or agent write is validated against the new state. Flipping Active off behaves like archiving: new submissions naming the slug fail with 422, existing assignments keep matching until they change.
  • Archive or restore a slug — archive is a soft-delete: the row stays for analytics and audit, the slug leaves the accepted set, and confirmation is required. Restore (under Show archived) flips it back to active with no confirmation step, because the operation is non-destructive.
  • Remove a skill from an agent mid-routing — the agent drops out of eligibility for queues requiring that skill on the next dispatch tick. Calls already bridged to them are unaffected; only new dispatch decisions see the change.
  • Hot-add a skill — the reverse: the agent becomes eligible on the next tick. Waiting callers are re-evaluated on the tick after the assignment lands, so a hot-add can pick up a queued call within one dispatch cycle.
Because archive is soft, an audit review can always answer “what did this slug mean when the call matched?” — the historical row remains readable for reporting, and every register/edit/archive/restore writes the before/after values to the audit ledger.

​
4. Limits — where skills live and who manages them

  • Write access: the catalog page gates writes to owner, admin, and developer roles; other roles see the list without edit controls. Certification issue/renew/revoke stays with supervisor and admin roles. Keep both with supervisors as a tenant-owned control, mirroring the SOC 2 controls posture.
  • Per-agent bounds: an agent carries at most 32 skills (and at most 64 skill-proficiency entries); the dispatcher’s per-tick scan is bounded by that cap.
  • Slug contract: lowercase ASCII letters, digits, _, -, max 60 characters. The same rule applies on the dialog and the API, so a client-valid slug never round trips to a 422.
  • Drift risk: skills, teams, and queues are three different groupings. A queue requiring a slug no agent holds deadlocks until overflow — audit with GET /api/v1/voice/skill-catalog?includeInactive=true before queue go-lives and after bulk roster changes to catch drift between the catalog and assignments.
  • Recover from a 422 UNKNOWN_SKILL: read the rejected slugs named in the error (up to ten in the message, the full set in the error details), register them in the catalog or correct the spelling, and retry the queue or agent write. The same check runs on queue creation, queue patch, agent skill assignment, and certification issue — and an empty skill list is always valid.
Related guides: