service-omni-work-skill-routing-configure — Claude Code skill
The service-omni-work-skill-routing-configure Claude Code skill configures Omni routing from a record field value. For example, it can require the Voice skill when Case.Origin is Phone.
Apache-2.0 100 installs ★ 1,183 updated 2026-10-23
npx skills add forcedotcom/sf-skills --skill service-omni-work-skill-routing-configure -a claude-codeWhat service-omni-work-skill-routing-configure does
The skill creates a WorkSkillRouting rule that selects a required Omni Skill from a field on the related work record. Its scripts/configure-and-report.sh script takes an org, entity, field, skill, and value; each run adds one mapping. There is one rule per entity. Repeating the same mapping reuses the rule, while a new mapping joins its existing attributes.
Setup needs an org authenticated with sf, a Service Cloud license, sf version 2.139.6 or later, skills-based routing enabled, and the referenced Skill already created. It also requires jq 1.6 or later and python3 3.8 or later. The skill checks that the target is not a production org, reads existing metadata through the Tooling API, then deploys through the Metadata API. Values containing XML-reserved characters are unsupported; an invalid field or value blocks deployment.
What it helps with
- route
Caserecords by the value ofOrigin - require an Omni skill for a field value
- add a field-to-skill mapping to an existing routing rule
- change one mapping while preserving other attributes
Example prompts for the agent
- Set routing so
Case.Origin = Phonerequires theVoiceskill. - Map a
MessagingSessionfield value to the required Omni Skill. - Add an Omni skill-routing rule for
Caseusing theOriginfield.
How to install service-omni-work-skill-routing-configure
1Skills CLI (Vercel)
npx skills add forcedotcom/sf-skills --skill service-omni-work-skill-routing-configure -a claude-code2Manually: put the files in place
~/.claude/skills/service-omni-work-skill-routing-configure/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/service-omni-work-skill-routing-configure/
1Skills CLI (Vercel)
npx skills add forcedotcom/sf-skills --skill service-omni-work-skill-routing-configure -a codex2Manually: put the files in place
.agents/skills/service-omni-work-skill-routing-configure/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add forcedotcom/sf-skills --skill service-omni-work-skill-routing-configure -a cursor2Manually: put the files in place
.cursor/skills/service-omni-work-skill-routing-configure/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install forcedotcom/sf-skills skills/service-omni-work-skill-routing-configure2Manually: put the files in place
.github/skills/service-omni-work-skill-routing-configure/SKILL.md1Skills CLI (Vercel)
npx skills add forcedotcom/sf-skills --skill service-omni-work-skill-routing-configure -a gemini-cli2Platform CLI
gemini skills install https://github.com/forcedotcom/sf-skills --path skills/service-omni-work-skill-routing-configureManually: put the files in place
.devin/skills/service-omni-work-skill-routing-configure/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add forcedotcom/sf-skills --skill service-omni-work-skill-routing-configure -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about service-omni-work-skill-routing-configure
How do I install service-omni-work-skill-routing-configure in Claude Code?
Run npx skills add forcedotcom/sf-skills --skill service-omni-work-skill-routing-configure -a claude-code. The skill file is at ~/.claude/skills/service-omni-work-skill-routing-configure/SKILL.md.
What does service-omni-work-skill-routing-configure do?
It creates a WorkSkillRouting rule that requires an Omni Skill when a record field matches a value. New mappings are merged into the existing rule's attributes.
What does service-omni-work-skill-routing-configure need to run?
It needs an authenticated Salesforce org with a Service Cloud license, sf 2.139.6 or later, jq 1.6 or later, and python3 3.8 or later. Skills-based routing must be enabled, and the referenced Skill must already exist.
Source text
SKILL.md · Apache-2.0
---
name: service-omni-work-skill-routing-configure
description: "Use to author an Omni WorkSkillRouting rule (field-based skill criteria): map a related-entity field value to a required Omni Skill (e.g. add the Voice skill when Case.Origin = Phone), deployed as one WorkSkillRouting record via the Metadata API. Idempotent via the Metadata API files[].state signal; one rule per related entity. Triggers: add field-based skill routing, route by a Case field to a skill, route by a MessagingSession field to a skill, configure attribute-based skills routing, require an Omni skill for a field value. Do not use to create the Skill or bind agents to it (service-omni-skills-based-routing-configure), to create agent users, or to configure queues."
allowed-tools: Bash Read Write Edit Glob Grep
metadata:
version: "1.0"
domains: ["Service"]
minApiVersion: "66.0"
relatedSkills:
- "service-omni-base-settings-configure"
- "service-omni-channel-setup-coordinate"
- "service-omni-skills-based-routing-configure"
accessCheck: "OrgPermissions.LightningService"
cliTools:
- tool: ["jq"]
semver: ">=1.6"
- tool: ["python3"]
semver: ">=3.8"
- tool: ["sf"]
semver: ">=2.139.6"
---
# service-omni-work-skill-routing-configure
Author an Omni **WorkSkillRouting** rule so work is routed to agents by a **field value on the work record**, not just by skills the agent happens to hold. Where `service-omni-skills-based-routing-configure` makes an agent *routable* (Skill + ServiceResource + ServiceResourceSkill), this skill decides *which skill a work item requires* based on one of its fields — for example "when `Case.Origin` = `Phone`, require the `Voice` skill". The rule is one `WorkSkillRouting` record (a header plus one `workSkillRoutingAttributes` mapping) deployed via the Metadata API. It runs after the referenced Skill exists and belongs to the same routing family coordinated by `service-omni-channel-setup-coordinate`.
## Inputs
```bash
bash scripts/configure-and-report.sh <org-alias> <related_entity> <field> <skill> <value> [rule_master_label]
```
- `org-alias` (required).
- `related_entity` (required). The sObject the rule applies to (e.g. `Case`, `MessagingSession`, `LiveChatTranscript`, `Lead`, `VoiceCall`).
- `field` (required). The field the attribute evaluates (e.g. `Case.Origin` or `Origin`). Bare standard fields are qualified with the related entity before deploy, so `Origin` becomes `Case.Origin` instead of being misread as a custom-field metadata name.
- `skill` (required). The Omni `Skill` DeveloperName required when the field matches (e.g. `Voice`).
- `value` (required). The field value that maps to the skill (e.g. `Phone`). Plain values only; XML-reserved characters are not supported.
- `rule_master_label` (optional). MasterLabel for the rule; defaults to `<related_entity> Skill Routing`.
Env overrides: `RULE_DEVELOPER_NAME` (fullName of the rule, default the related-entity name — one rule per entity), `IS_ACTIVE` (default `true`), `SKILL_LEVEL` (0–10), `SKILL_PRIORITY` (0–10, additional-skill drop order), `IS_ADDITIONAL_SKILL` (`true`/`false`).
## 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 referenced `Skill` already exists (`service-omni-skills-based-routing-configure`).
- The three-way `safe_to_write` production guard applies.
## Run
1. **safe_to_write** — query `Organization`; refuse to write to a real production org.
2. **Skill prereq** — query `Skill` by DeveloperName; if absent, block and point at `service-omni-skills-based-routing-configure`.
3. **Merge** — read the existing `WorkSkillRouting.Metadata` through the Tooling API, preserve unrelated attributes, and replace or append only the requested `(field, value)` mapping. An inconclusive read blocks the write; `WSR_REPLACE=1` is the explicit destructive-replacement escape hatch.
4. **Deploy** — materialize the merged `WorkSkillRouting` record (elements in XSD/alphabetical order) and deploy it via the Metadata API (async + poll to a terminal state).
5. **Classify** — read `files[].state` (`Created` / `Changed` / `Unchanged`) to report `created` / `updated` / `reused`.
## Behavior
**Idempotent + merge-safe.** WorkSkillRouting permits a single rule per related entity, so the rule's fullName defaults to the entity name. Re-running the same mapping reports `reused`; a new mapping is merged into the existing attribute list; changing the same field/value mapping updates only that entry. The skill never silently replaces an existing rule when its current metadata could not be read.
**Graceful degradation.** WorkSkillRouting is not provisioned on every org (some trials/CDOs). A deploy failure shaped like `INVALID_TYPE` / "not available" / "WorkSkillRouting" is reported as `blocked` with a clear limitation message and a pointer to base settings — the skill surfaces the limitation rather than crashing.
## Output contract
A single JSON object: `status` ∈ `created` | `updated` | `reused` | `blocked` (plus `action_needed` in plan mode), `rule` (`{developer_name, master_label, related_entity, is_active, state}`), `attribute` (`{field, skill, value, skill_level, skill_priority, is_additional_skill}`), `merge` (`{merged_from_existing, attribute_count, preserved_count}`), `deploy_id`, `manual_actions`, `blocking_issue`.
## Limitations
- One field→skill mapping per invocation and one rule per related entity. Multiple invocations safely accumulate attributes on that rule.
- Does not create the Skill, ServiceResources, agent users, queues, or presence configuration.
- Field/value correctness is validated by the platform at deploy time; an invalid field or value surfaces as a `blocked` deploy failure.
## References
| File | When to read |
|---|---|
| `references/api-notes.md` | WorkSkillRouting metadata shape, XSD element order, one-rule-per-entity constraint, attribute fields, and graceful-degradation triggers |
| `scripts/tests/test_work_skill_routing_contracts.py` | When validating changes — run `python3 scripts/tests/test_work_skill_routing_contracts.py` from this skill directory |
© forcedotcom · Apache-2.0 · forcedotcom/sf-skills