Skip to main content
skill CX Codex

service-omni-skills-based-routing-configure — Claude Code skill

service-omni-skills-based-routing-configure — a Claude Code skill links an Omni Skill to active agent users. It runs when setting up Omni skills-based routing.

Apache-2.0 106 installs ★ 1,183 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add forcedotcom/sf-skills --skill service-omni-skills-based-routing-configure -a claude-code
Open on GitHub

What service-omni-skills-based-routing-configure does

The skill checks for an Omni Skill and assigns it to active agents through SkillUser records. Existing skills and bindings are reused; only missing links are created, so reruns do not add duplicates.

It requires an authenticated sf CLI version 2.139.6 or later, a Service Cloud license, and skills-based routing enabled in Omni-Channel settings. The target agents must already exist and be active. Each run handles one skill.

This skill does not create agent users, queues, or WorkSkillRouting rules. SkillUser.SkillLevel stays at the platform default.

What it helps with

  • create an Omni Skill when it is missing
  • assign a skill to active agent users
  • add only missing SkillUser links
  • report agents whose skill assignment failed

Example prompts for the agent

  • Set up skills-based routing for Omni_Demo_Voice and the agents in agent_members.csv in org my-org.
  • Link the existing Omni Skill to active agents 005000000000001 and 005000000000002 in my-org.
  • Repair missing Omni_Demo_Voice assignments for active agents in org my-org.

How to install service-omni-skills-based-routing-configure

1Skills CLI (Vercel)

npx skills add forcedotcom/sf-skills --skill service-omni-skills-based-routing-configure -a claude-code

2Manually: put the files in place

~/.claude/skills/service-omni-skills-based-routing-configure/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/service-omni-skills-based-routing-configure/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about service-omni-skills-based-routing-configure

How do I install service-omni-skills-based-routing-configure in Claude Code?

Run npx skills add forcedotcom/sf-skills --skill service-omni-skills-based-routing-configure -a claude-code. The skill file will be at ~/.claude/skills/service-omni-skills-based-routing-configure/SKILL.md.

What does service-omni-skills-based-routing-configure do?

It creates an Omni Skill if needed and associates it with active agent users through SkillUser records. Existing records are reused.

What does service-omni-skills-based-routing-configure require?

It needs an authenticated sf CLI version 2.139.6 or later, a Service Cloud license, Omni-Channel skills-based routing enabled, and existing active agent users.

Source text

SKILL.md · Apache-2.0
---
name: service-omni-skills-based-routing-configure
description: "Use to make agents routable by Omni skills-based routing: ensure an Omni Skill exists, then assign it to each active agent through the classic Omni-Channel SkillUser junction. Idempotent — existing skills and user bindings are reused, and only missing bindings are created. Works on Service Cloud orgs without requiring Field Service. Triggers: set up skills-based routing agents, assign Omni skills to agents, make agents skill-routable, create an Omni skill and bind users, repair missing agent skill assignments. Do not use to author WorkSkillRouting rules, create agent users, or configure queues."
allowed-tools: Bash Read Write Edit Glob Grep
metadata:
  version: "1.0"
  domains: ["Service"]
  minApiVersion: "66.0"
  relatedSkills:
    - "service-omni-agent-users-create"
    - "service-omni-base-settings-configure"
  accessCheck: "OrgPermissions.LightningService"
  cliTools:
    - tool: ["jq"]
      semver: ">=1.6"
    - tool: ["python3"]
      semver: ">=3.8"
    - tool: ["sf"]
      semver: ">=2.139.6"
---

# service-omni-skills-based-routing-configure

Make agents routable by Omni **skills-based routing (SBR)**. A routable agent needs the **Skill** and a **SkillUser** junction assigning that skill to the agent's user. `SkillUser` is the classic Omni-Channel model written by Setup > Skills > Assign Users and evaluated when work has skill requirements. This skill ensures both, idempotently, for one skill across a set of active agent users.

`ServiceResource` and `ServiceResourceSkill` are the Field Service skill model. On a plain Service Cloud org, `ServiceResource.IsActive` is not writable or queryable, so a newly created resource remains inactive and the junction is rejected. This skill therefore uses the supported, license-appropriate `SkillUser` path.

## Inputs

```bash
bash scripts/configure-and-report.sh <org-alias> <skill_developer_name> [agent_members_csv] [skill_master_label]
```

- `org-alias` (required).
- `skill_developer_name` (required). The Omni `Skill` DeveloperName to ensure and bind (e.g. `Omni_Demo_Voice`).
- `agent_members_csv` (optional). Comma-separated agents to make skill-routable — each token a Username (`…@…`) or a 15/18-char User Id (`005…`). May also be supplied via `AGENT_MEMBERS_CSV`. When omitted, the skill blocks (it will not guess which agents to skill).
- `skill_master_label` (optional). MasterLabel used only when the skill must be created; defaults to a title-cased form of the DeveloperName.

## Preconditions and safety

- Target org authenticated via `sf` CLI, Service Cloud license, `sf` CLI ≥ 2.139.6.
- Omni-Channel base settings enabled with **skills-based routing** turned on (`service-omni-base-settings-configure`).
- The named agents exist and are active (`service-omni-agent-users-create`).
- The three-way `safe_to_write` production guard applies.

## Run

`configure-and-report.sh` proceeds in two idempotent phases, each detect-before-write:

1. **Skill** — query `Skill` by DeveloperName. Present → reused; absent → deploy a `Skill` component via the Metadata API and re-query for its Id.
2. **SkillUser** — query existing `SkillUser` records for the Skill and resolved users, then create only missing (`SkillId`, `UserId`) bindings via REST DML. A concurrent `DUPLICATE_VALUE` is reconciled as reused.

## Behavior

**Idempotent + non-destructive.** Existing skills and bindings are reused; the skill never deletes or reassigns anything it did not create, so re-runs converge without duplication. Only **active** users are resolved — an inactive user cannot be routed work, so it is reported rather than silently skilled.

**Partial safety.** If some bindings succeed and others fail, the status is `partial` with per-agent errors in `blocking_issue`; the successful bindings are left in place (each junction is an independent write).

## Output contract

A single JSON object: `status` ∈ `configured` | `reused` | `partial` | `blocked`, `skill` (`{developer_name, id, state}`), `agents` (array of `{username, user_id, skill_binding_id, skill_binding_state}`), `created_counts`, `reused_counts`, `manual_actions`, `blocking_issue`.

- `reused` — skill and all bindings already existed.
- `configured` — at least one component created and all requested bindings now exist.
- `partial` / `blocked` — see `blocking_issue`; `manual_actions` names the prerequisite skill when the cause is a missing precondition.

## Limitations

- One skill per invocation; run again per skill an agent set needs.
- Does not author `WorkSkillRouting` rules or field-based skill criteria — that is a separate skill.
- Does not create agent users, queues, or presence configuration.
- `SkillUser.SkillLevel` is left at the platform default; forking the DML body is required to set explicit proficiency.

## References

| File | When to read |
|---|---|
| `references/api-notes.md` | Skill metadata vs Skill sObject, the SkillUser agent-binding model, and SBR base-setting prerequisites |
| `scripts/tests/test_sbr_contracts.py` | When validating changes — run `python3 scripts/tests/test_sbr_contracts.py` from this skill directory |

© forcedotcom · Apache-2.0 · forcedotcom/sf-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set232

The whole set →
service-omni-queue-routing-config-deploy The service-omni-queue-routing-config-deploy Claude Code skill creates or updates Salesforce Omni-Channel queue routing settings. It runs for Case or Voice queue setup and when deploying a QueueRoutingConfig. CX Codex +1 108installs platform-metadata-discovery-get platform-metadata-discovery-get is a Claude Code skill that checks which Salesforce metadata already exists in an org. It runs before metadata changes or code that refers to org metadata. CX Codex +1 107installs service-omni-service-channel-configure service-omni-service-channel-configure is a Claude Code skill that finds or creates a ServiceChannel for Case, Incident, MessagingSession, or VoiceCall. It runs during Omni-Channel routing setup. CX Codex +1 106installs service-omni-queue-members-assign service-omni-queue-members-assign — a Claude Code skill that assigns agent users to Salesforce queues via the Data API. Populates Case and Voice queues so Omni-Channel routing can distribute work items. CX Codex +1 106installs service-omni-permission-set-assign service-omni-permission-set-assign — a Claude Code skill that assigns Omni permission sets to provisioned agents. It runs on requests to grant Omni-Channel access or fix permissions for the Omni widget. CX Codex +1 104installs service-omni-supervisor-config-deploy The service-omni-supervisor-config-deploy Claude Code skill deploys a classic Omni-Channel Supervisor configuration to Salesforce. It runs on requests to set up Omni Supervisor or the Supervisor Command Center. CX Codex +1 104installs service-omni-sidebar-configure service-omni-sidebar-configure — a skill for Claude Code enables and validates the pinned Omni-Channel sidebar on Lightning console apps. Configures the pinned utility view directly in CustomApplication metadata. CX Codex +1 103installs service-omni-presence-status-deploy The service-omni-presence-status-deploy Claude Code skill deploys Omni-Channel presence statuses. It runs for requests to create an Available status for Case, Incident, Messaging, or Voice, or to add the standard Busy status. CX Codex +1 103installs

Project sponsors

Companies that keep this analytics open