Skip to main content
skill CX Codex

service-omni-permission-set-assign — Claude Code skill for Omni access

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.

Apache-2.0 104 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-permission-set-assign -a claude-code
Open on GitHub

What service-omni-permission-set-assign does

The skill finds agent users and assigns permission sets through PermissionSetAssignment. Its default target is Omni_Agent; it checks current assignments, creates only missing ones, then queries Salesforce again to confirm the result. It handles individual PermissionSet records, not PermissionSetGroup, and never removes existing assignments.

The target org must be authenticated, have a Service Cloud license, and be accessible with sf CLI version 2.139.6 or later and jq version 1.6 or later. The operator needs PermissionsAssignPermissionSets. Agent users must already exist, and at least one Omni presence status must be deployed before the skill can self-heal Omni_Agent; service-omni-presence-status-deploy deploys those statuses.

Production org assignments are blocked with no override because they can raise a real user's privileges. Self-healing deploys only the bundled Omni_Agent; other permission sets must already exist. Each missing pair gets its own request, followed by a Salesforce query to verify the assignments.

What it helps with

  • grant agents access to the Omni widget
  • add Omni-Channel permissions to agent users
  • create missing Omni_Agent assignments
  • assign several permission sets across the agent group

Example prompts for the agent

  • Assign Omni_Agent to the three provisioned agents.
  • Fix missing Omni permissions for the agents and grant them Omni-Channel access.
  • Prepare the agents to use the Omni widget by assigning Omni_Agent.

How to install service-omni-permission-set-assign

1Skills CLI (Vercel)

npx skills add forcedotcom/sf-skills --skill service-omni-permission-set-assign -a claude-code

2Manually: put the files in place

~/.claude/skills/service-omni-permission-set-assign/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/service-omni-permission-set-assign/

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

Questions about service-omni-permission-set-assign

How do I install service-omni-permission-set-assign in Claude Code?

Run npx skills add forcedotcom/sf-skills --skill service-omni-permission-set-assign -a claude-code. The skill file is at ~/.claude/skills/service-omni-permission-set-assign/SKILL.md.

What does service-omni-permission-set-assign do?

It assigns Omni_Agent or other existing permission sets to agent users, skipping assignments already in place. It then checks the final state through Salesforce.

What does service-omni-permission-set-assign require?

It requires an authenticated org with a Service Cloud license, sf CLI 2.139.6 or later, jq 1.6 or later, and the PermissionsAssignPermissionSets permission. Agent users and at least one Omni presence status must already exist.

Source text

SKILL.md · Apache-2.0
---
name: service-omni-permission-set-assign
description: "Assign the required Omni permission sets to provisioned agent users. TRIGGER when users ask to assign Omni permissions to agents, grant Omni-Channel access, add Omni_Agent permissions, repair missing Omni permission assignments, or prepare agents to use the Omni widget. DO NOT TRIGGER for arbitrary permission-set authoring, agent creation, or queue membership."
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-presence-status-deploy"
    - "service-omni-queue-members-assign"
  accessCheck: "OrgPermissions.LightningService"
  cliTools:
    - tool: ["jq"]
      semver: ">=1.6"
    - tool: ["sf"]
      semver: ">=2.139.6"
---

# service-omni-permission-set-assign

Assign one or more PermissionSets to N agent users via `PermissionSetAssignment` Data API POSTs. The default target is `Omni_Agent`, the permission set granting the OmniChannel widget, presence-status access, and demo-queue visibility — without an assignment row, agents cannot open the widget or receive routed work. Detection is SOQL-based, so the skill only creates the assignments that are missing. Agent users come from `service-omni-agent-users-create`, and it runs alongside `service-omni-presence-status-deploy` so assigned agents can both open the widget and select a status.

## Inputs

```bash
bash scripts/verify-and-assign.sh <org-alias> [count=3] [permission-set-names-csv=Omni_Agent]
```

- `org-alias` (required).
- `count` (optional, default `3`, range `1..10`) — must match the agent user count.
- `permission-set-names-csv` (optional, default `Omni_Agent`) — comma-separated for multiple. Every user gets every listed set (cross-product): `count=3` × 2 sets = up to 6 assignments.

## Preconditions and safety

- Target org authenticated via `sf` CLI, Service Cloud license, `sf` CLI ≥ 2.139.6.
- The agent users exist (`service-omni-agent-users-create`); a count mismatch blocks with a pointer back to that skill.
- The executing user has `PermissionsAssignPermissionSets` (standard on System Administrator) — required even for org admins; `ModifyAllData` alone is insufficient.
- At least one Omni presence status exists before `Omni_Agent` self-heals — the bundled set grants agent capability via `servicePresenceStatusAccesses` for whichever curated statuses exist (e.g. `Available_Case`/`Available_Voice` + `Busy`), generated at deploy time. Run `service-omni-presence-status-deploy` first; the coordinator sequences presence before permset for this reason.
- The three-way `safe_to_write` guard applies — assigning permission sets on a production org can escalate a real user's privileges, so it blocks with no override.

**Self-heal (run mode only).** When the default `Omni_Agent` set is absent, the skill deploys the bundled `Omni_Agent` metadata once, then assigns. In `--plan` mode it never deploys — it reports `action_needed` and exits read-only. This covers only the bundled `Omni_Agent` asset; any other permission set must already exist or the run blocks with a click-path.

## Run

`verify-and-assign.sh` performs the whole cycle:

1. Compute `safe_to_write`; derive the 8-char org suffix.
2. Resolve the agent users by the `agent{1..N}.<suffix>@example.com` pattern; block if any are missing.
3. Resolve each `PermissionSet` by name; self-heal `Omni_Agent` if absent, else block naming which is missing.
4. Query existing `PermissionSetAssignment` for the (user × set) cross-product; compute the missing pairs.
5. POST one assignment per missing pair (individual POSTs, no `allOrNone`).
6. Re-query to confirm final state and emit the report.

## Behavior

**Cross-product.** Every user gets every listed set; a partial assignment is a failure, not a feature.

**Idempotency.** `PermissionSetAssignment` has a database uniqueness constraint on (AssigneeId, PermissionSetId), so a re-POST raises `DUPLICATE_VALUE`; the skill detects existing pairs first and treats `DUPLICATE_VALUE` as a safety net for concurrent races. It POSTs individually so one duplicate or error never rolls back its successful siblings, and it re-queries after all POSTs — a 201 only means Salesforce accepted the write; a subsequent SOQL confirms the assignment is active.

**Non-destructive.** The skill is create-only; it never deletes existing assignments (users may hold out-of-band permissions from other admins) and derives users from the agent pattern rather than accepting an explicit user-id list, so it never assigns demo permissions to real named users.

## Output contract

A single JSON object with `status` ∈ `assigned` | `reused` | `partial` | `blocked`, the resolved `permission_sets`, `org_suffix`, `requested_count`, `expected_assignment_count` (= `requested_count × len(permission_sets)`), a `before` snapshot, `assigned_this_run`/`assigned_count`, `reused_count`, an `after` snapshot, `manual_actions`, and `blocking_issue`.

- `assigned` — at least one new assignment created; all expected pairs exist after.
- `reused` — all expected pairs already existed; nothing POSTed.
- `partial` — some POSTs failed; final count is below expected.
- `blocked` — precondition failed (production org, missing set, missing users, missing permissions).

`assigned_count + reused_count == expected_assignment_count` unless `partial`; `blocking_issue` is non-null only for `blocked`/`partial`.

## Limitations

- Assigns individual PermissionSets only — a `PermissionSetGroup` is a different sObject and is out of scope.
- Self-heal covers only the bundled `Omni_Agent`; it is not a general-purpose permission-set authoring surface.
- Create-only; it does not remove assignments.

## References

| File | When to read |
|---|---|
| `assets/package.xml` | Load when the default `Omni_Agent` permission set is missing and the run-mode self-heal path must deploy the bundled metadata |
| `references/api-notes.md` | Before the POST loop — PermissionSetAssignment schema, its `DUPLICATE_VALUE` semantics, and why users are derived from the agent pattern rather than an explicit id list |

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

Similar skills

SKILL.md skills catalog →

From the same set232

The whole set →
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-skills-based-routing-configure 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. CX Codex +1 106installs 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 service-omni-base-settings-configure service-omni-base-settings-configure — a skill for Claude Code that configures Salesforce Omni-Channel base settings via the Metadata API. Deploys the five primary routing booleans required before setting up queues. CX Codex +1 103installs

Project sponsors

Companies that keep this analytics open