Skip to main content

​
Voice → Skill Catalog operator workflow

Skills-based routing only works when every tag means the same thing everywhere. The Voice → Skill catalog page (/voice/skill-catalog) is the governance surface for your tenant’s canonical skill universe: queues and agents are configured against it, and a submission referencing an unregistered skill is rejected at write time — instead of silently deadlocking dispatch on a call that never matches. This guide walks the operator workflow: register a skill, edit and archive it, and recover from the 422 the write path raises on an unknown slug.

​
Why the catalog is a gate, not a suggestion

A queue declares the skills it requires; an agent carries the skills they hold; the dispatcher intersects the two on a string match at every dispatch tick. If a skill string is accepted without a registered catalog row, a mistyped tag enters the system and never bridges:
  1. A queue requiring spainsh never matches an agent holding the spanish skill — the caller waits until overflow.
  2. No error surfaces, because dispatch sees an empty eligibility set as normal.
The catalog closes that failure at the configuration boundary. Queue and agent skill assignments pass through the write-path validation, and an unknown slug returns 422 UNKNOWN_SKILL naming the rejected skill rather than persisting it.

​
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.

​
Edit a skill

The Edit action on each row patches the label, description, or active state — the slug stays fixed. Setting description to empty in the dialog clears the field (an explicit null on the PATCH). Flipping Active off takes the skill out of validation, exactly like archiving.

​
Archive and restore

Archive is a soft-delete: the row is kept for analytics and audit, flagged inactive, and no longer assignable — new queue and agent submissions that name it fail validation, while existing assignments remain readable for reporting. Re-registering the same slug is allowed because only active rows occupy the uniqueness slot. Archive asks for confirmation before it fires. Restore (available once Show archived is on) flips the row back to active with no confirmation step, because the operation is non-destructive.

​
Recover from a 422 UNKNOWN_SKILL

When a queue save or agent skill update fails with 422 UNKNOWN_SKILL:
  1. Read the rejected slugs in the error message — the response names them (up to ten in the message, the full set in the error details).
  2. Either correct the spelling to the registered slug, or register the missing skill in the catalog first.
  3. Retry the queue or agent write.
The same check runs on queue creation, queue patch, and agent skill assignment, so the fix path is identical everywhere. An empty skill list is always valid — it is the wildcard “any skill” membership — and the gate never rejects it.

​
Audit and role gating

Every register, edit, archive, and restore writes to the audit ledger with the before/after values, so catalog governance is provable to an auditor. The page gates writes to owner, admin, and developer roles (readers see the list without edit controls) — keep management of the catalog with supervisors as your tenant-owned control, mirroring the SOC 2 controls posture. Related guides: