> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice → Skill Catalog operator workflow

> Register, edit, archive, and restore the skills that skills-based routing validates against — plus the recovery workflow when a queue or agent write returns 422 UNKNOWN_SKILL.

# 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:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/voice/skill-catalog \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug": "spanish", "label": "Spanish", "description": "Spanish-language support"}'
```

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](/compliance/soc2-controls) posture.

Related guides:

* [The skill catalog: the canonical list of skills routing accepts](/concepts/skill-catalog) — validation boundary, endpoint contract, certifications, proficiency decay.
* [Voice queues](/guides/voice-queues) — staffing queues with skill-tagged members.
* [Skill certifications](/guides/voice-skill-certifications) — expiry-dated per-skill credentials for regulated queues.
* [Audit log](/guides/audit-log) — browsing and exporting the ledger.