service-omni-presence-user-config-deploy — Claude Code skill
The service-omni-presence-user-config-deploy Claude Code skill deploys an Omni presence configuration for agents. It sets decline handling and an ACW timer, then assigns the configuration to users.
Apache-2.0 102 installs ★ 1,183 updated 2026-10-23
npx skills add forcedotcom/sf-skills --skill service-omni-presence-user-config-deploy -a claude-codeWhat service-omni-presence-user-config-deploy does
The skill deploys a PresenceUserConfig and its PresenceDeclineReason together in one Metadata API package. It turns Auto-Accept off, enables Decline and Decline Reason, and sets an After-Conversation-Work timer with a maximum duration. Agents can be supplied by username or User ID; the script resolves IDs to usernames.
Running it requires an authenticated target org, a Service Cloud license, sf version 2.139.6 or later, and enabled Omni-Channel base settings. It also uses jq version 1.6 or later and python3 version 3.8 or later. If PRESENCE_STATUS_ON_DECLINE is set, that ServicePresenceStatus must already exist.
Each run handles one presence configuration. Other configurations and decline reasons remain untouched, and a later run uses Metadata API component state to detect unchanged records. The skill does not configure the ACW timer on a ServiceChannel or grant status access through a permission set.
What it helps with
- deploy an Omni presence configuration with its decline reason
- enable agent decline handling and an ACW timer in one record
- assign a presence configuration using usernames or User IDs
- rerun deployment while reusing unchanged components
Example prompts for the agent
- Create an Omni presence configuration for agents with decline handling and a decline reason.
- Set an ACW timer and assign the configuration to users
[email protected]. - Deploy a presence configuration for User ID
005XXXXXXXXXXXXXXX.
How to install service-omni-presence-user-config-deploy
1Skills CLI (Vercel)
npx skills add forcedotcom/sf-skills --skill service-omni-presence-user-config-deploy -a claude-code2Manually: put the files in place
~/.claude/skills/service-omni-presence-user-config-deploy/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/service-omni-presence-user-config-deploy/
1Skills CLI (Vercel)
npx skills add forcedotcom/sf-skills --skill service-omni-presence-user-config-deploy -a codex2Manually: put the files in place
.agents/skills/service-omni-presence-user-config-deploy/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add forcedotcom/sf-skills --skill service-omni-presence-user-config-deploy -a cursor2Manually: put the files in place
.cursor/skills/service-omni-presence-user-config-deploy/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install forcedotcom/sf-skills skills/service-omni-presence-user-config-deploy2Manually: put the files in place
.github/skills/service-omni-presence-user-config-deploy/SKILL.md1Skills CLI (Vercel)
npx skills add forcedotcom/sf-skills --skill service-omni-presence-user-config-deploy -a gemini-cli2Platform CLI
gemini skills install https://github.com/forcedotcom/sf-skills --path skills/service-omni-presence-user-config-deployManually: put the files in place
.devin/skills/service-omni-presence-user-config-deploy/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add forcedotcom/sf-skills --skill service-omni-presence-user-config-deploy -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-presence-user-config-deploy
How do I install service-omni-presence-user-config-deploy in Claude Code?
Run npx skills add forcedotcom/sf-skills --skill service-omni-presence-user-config-deploy -a claude-code. The skill file will be at ~/.claude/skills/service-omni-presence-user-config-deploy/SKILL.md.
What does service-omni-presence-user-config-deploy do?
It deploys a PresenceUserConfig and its related PresenceDeclineReason in one Metadata API package. The configuration enables decline handling and an ACW timer, then assigns the config to the specified agents.
What does service-omni-presence-user-config-deploy require?
It requires an authenticated org with a Service Cloud license, enabled Omni-Channel base settings, sf version 2.139.6 or later, jq version 1.6 or later, and python3 version 3.8 or later. Any PRESENCE_STATUS_ON_DECLINE value must refer to an existing status.
Source text
SKILL.md · Apache-2.0
---
name: service-omni-presence-user-config-deploy
description: "Use to deploy an Omni PresenceUserConfig (presence configuration) as one whole-record Metadata write with the decline/ACW fields set consistently: Auto-Accept off, Decline on, Decline Reason on (with a PresenceDeclineReason deployed in the same package), and an After-Conversation-Work wrap-up timer. Agents are assigned by username. Idempotent via the Metadata API files[].state signal. Triggers: create presence configuration, enable decline + decline reason + ACW wrap-up timer for agents, assign presence config to users. Do not use for ServicePresenceStatus (separate skill), for permission-set access to statuses, or to set the channel-level ACW timer on a ServiceChannel."
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"
- "service-omni-channel-setup-coordinate"
- "service-omni-presence-status-deploy"
accessCheck: "OrgPermissions.LightningService"
cliTools:
- tool: ["jq"]
semver: ">=1.6"
- tool: ["python3"]
semver: ">=3.8"
- tool: ["sf"]
semver: ">=2.139.6"
---
# service-omni-presence-user-config-deploy
Deploy an Omni **PresenceUserConfig** (the "presence configuration" that governs how work is offered to agents) together with the **PresenceDeclineReason** it references, in one atomic Metadata API package. The decline / auto-accept / decline-reason / ACW fields have cross-field validators — enabling Decline requires Auto-Accept off, Decline Reason requires Decline on, and the ACW timer must be paired with its max time — so they can only be set correctly as a **single whole-record write**, not field-by-field. This skill encodes that consistent record and assigns it to the given agents. It runs after `service-omni-agent-users-create` / `service-omni-presence-status-deploy` and is invoked by `service-omni-channel-setup-coordinate` as a rep-experience step.
## Inputs
```bash
bash scripts/deploy-and-report.sh <org-alias> [config_developer_name] [agent_usernames_csv]
```
- `org-alias` (required).
- `config_developer_name` (optional, default `Omni_Demo_Presence_Config`).
- `agent_usernames_csv` (optional). Comma-separated Usernames (`…@…`) and/or 15/18-char User Ids (`005…`) to assign; Ids are resolved to usernames (metadata assigns by username). May also be set via `AGENT_USERNAMES_CSV`. Empty → the config deploys with no user assignments.
Env overrides: `DECLINE_REASON_LABEL` (default `Training`), `DECLINE_REASON_DEVELOPER_NAME` (default derived from the label), `CAPACITY` (default `5`, 1–100), `ACW_SECONDS` (default `60`, 10–3600), `PRESENCE_STATUS_ON_DECLINE` (optional ServicePresenceStatus DeveloperName).
## Preconditions and safety
- Target org authenticated via `sf` CLI, Service Cloud license, `sf` CLI ≥ 2.139.6.
- Omni-Channel base settings enabled (`service-omni-base-settings-configure`).
- Any `PRESENCE_STATUS_ON_DECLINE` must already exist (`service-omni-presence-status-deploy`).
- The three-way `safe_to_write` production guard applies.
## Run
`deploy-and-report.sh` materializes two components into a temp DX project and deploys them in one call:
1. `PresenceDeclineReason:<reason>` — the decline reason (label only).
2. `PresenceUserConfig:<config>` — capacity + label, `enableAutoAccept=false`, `enableDecline=true`, `enableDeclineReason=true`, `declineReasons=<reason>`, `hasAfterConvoWorkTimer=true`, `afterConvoWorkMaxTime=<ACW_SECONDS>`, optional `presenceStatusOnDecline`, and `assignments/users` for the resolved agents.
Elements are emitted in strict XSD order. Idempotency comes from the Metadata API `files[].state` per component (`Unchanged`→reused, `Changed`→updated, `Created`→created); the deploy runs `--async` and polls to a terminal state.
## Behavior
**Whole-record + consistent.** The record is always emitted with the validator-safe combination, so a re-deploy is a clean no-op rather than a field diff that could trip a cross-field rule.
**Non-destructive.** Only the named config and decline reason are written; other presence configs and decline reasons on the org are never touched. Assignments are declared for the resolved agents; the skill does not remove users it did not add (a redeploy declares the full assignment set for this config).
## Output contract
A single JSON object: `status` ∈ `created` | `updated` | `reused` | `blocked`, `config` (`{developer_name, label, capacity, acw_seconds, state}`), `decline_reason` (`{developer_name, label, state}`), `assigned_usernames`, `deploy_id`, `manual_actions`, `blocking_issue`.
## Limitations
- One presence configuration per invocation.
- Encodes the decline+ACW rep profile from the steel thread; other field combinations require forking the XML template.
- Does **not** set the channel-level After-Conversation-Work timer on a `ServiceChannel` (a separate concern), deploy `ServicePresenceStatus`, or grant status access via permission set.
## References
| File | When to read |
|---|---|
| `references/api-notes.md` | PresenceUserConfig cross-field validators, XSD element order, decline-reason packaging, and ACW field pairing |
| `scripts/tests/_bootstrap.py` | Test bootstrap loaded by the contract suite to locate the skill root and run its shell entry point |
| `scripts/tests/test_presence_user_config_contracts.py` | Run after changing the deployment script to verify guard, whole-record, membership, and output contracts |
© forcedotcom · Apache-2.0 · forcedotcom/sf-skills