forcedotcom/sf-skills / plugins/builder/service-itsm/skills/service-itsm-agentic-setup-employee-agent-configure
service-itsm-agentic-setup-employee-agent-configure
UnverifiedCreate and activate an IT Service Employee agent as a Next-Gen Authoring (NGA) native agent from an ITSM Employee agent template's Agent Script, via the Salesforce CLI (sf): read the template, check idempotency, create the NGA bundle then publish and activate, verify live. Defaults to the broad IT Service Employee template; when the user names a specialized Employee template (Password Manager Assistance, Certificate Management, Onboarding, Hardware Request, and ~47 others catalogued in references/specialized-templates.md — all under the `svc_emp_intelligence__` namespace), pins that one instead. Idempotent per developer name. TRIGGER when the user asks to create/set up/provision/activate the Employee agent, the IT Service Employee agent, or a specialized Employee agent (password manager, certificate, onboarding, hardware request, etc.). DO NOT TRIGGER: prerequisite checks (service-itsm-agentic-setup-agentforce-studio-validate), CMDB CRUD, Fulfiller setup (service-itsm-agentic-setup-fulfiller-agent-configure).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 29.4 KB |
| references/cli-invocation.md | markdown | 22.4 KB |
| references/error-taxonomy.md | markdown | 4.1 KB |
| references/reactivation.md | markdown | 4.2 KB |
| references/report-format.md | markdown | 4.9 KB |
| references/specialized-templates.md | markdown | 10.5 KB |
| references/workflow-detail.md | markdown | 18.2 KB |
| scripts/build-create-body.mjsexecutable | script | 4.7 KB |
| scripts/classify-agent-existence.mjsexecutable | script | 13.5 KB |
| scripts/classify-preflight.mjsexecutable | script | 11.4 KB |
| scripts/create-scratch-dir.mjsexecutable | script | 2.3 KB |
| scripts/render-report.mjsexecutable | script | 12.2 KB |
references/error-taxonomy.md
View on GitHub# Error taxonomy and gotchas — Create the IT Service Employee Agent
Split from `references/cli-invocation.md` — that file documents the per-phase
CLI call shapes and the classifier contracts; this file collects the errors
those calls can return and the recurring foot-guns.
## Error taxonomy
- **Auth error / `401 Unauthorized`** — the org session is expired or the alias
is wrong. Re-run `sf org login web` for the target org; there is no token to
refresh by hand.
- **`401`/`403`/unexpected error body on the Phase-1 Studio-access read** — the
preflight classifier maps this to `studio.signal="ERROR"` / `verdict="ERROR"`
(distinct from a confirmed 404 gate). Surface the raw response and stop —
do not proceed to Phase 2 even if the template read succeeded.
- **`403`/`404` on `createBundleWithVersion` / `publish` / `activate`** — the
NGA authoring namespace isn't provisioned or enabled on the org. Trigger the
Phase-1 hand-off offer.
- **`400 MISSING_ARGUMENT: agentType`** on `agent-templates` — the required
`agentType` query param was omitted; pass `AgentforceEmployeeAgent`.
- **Build-script exit 3** — the template, its `agentScript`, or a successful
`developer_name`/`agent_label` substitution wasn't found in the captured
`agent-templates.json`; surface stderr, don't hand-author a body.
- **Classifier exit 3** on a `sf data query` read — the SOQL query failed
(auth/malformed); surface the raw CLI error, do not treat as NOT-EXISTS.
- **Empty stdout from `activate`** — this is the SUCCESS response
(`EmptyRepresentation`), not a failure; confirm via the Phase-7 verify SOQL.
## Gotchas
| Issue | Resolution |
|-------|------------|
| Legacy `createAgent` produces the wrong kind of agent | Never call `/connect/service-itsm/createAgent` — it creates a Setup-page bot with an external-link icon in Agentforce Studio. Use the three `/nextgen-authoring/*` calls in `references/cli-invocation.md` |
| `sf api request rest --method POST` with no `--body` flag | Fails with `No 'mode' found in 'body' entry`, even for `publish`/`activate` which ignore the body — always pass `--body '{}'` explicitly |
| `sf api request rest --json` errors | Don't pass `--json` there — the raw stdout body is already JSON. `--json` is for `sf data query` (which needs the `.result.records[]` envelope) |
| Confusing `bundleId` with `bundleVersionId` | The `createBundleWithVersion` response's `id` field is the bundle **version** Id used in publish/activate; `bundleId` is the parent bundle's Id and 404s if passed to `/bundle-versions/{...}` |
| Naive single-pass HTML-entity decode leaves compile errors | `"` (double-encoded) and `\` (numeric, backslash) require a multi-pass decode covering both named and numeric entities — see `build-create-body.mjs` |
| Bundle's outer `apiName` diverging from the script's internal `config.developer_name` | Always substitute both via `build-create-body.mjs` before the create call — a divergence is exactly the kind of mismatch that produces confusing platform behavior |
| Hardcoding `IT_Service_Employee_Agent` in one call but collecting it in another | Thread the collected `<developerName>` through the idempotency SOQL, the bundle body (outer + internal), AND the verify SOQL — a mismatch creates the wrong agent |
| Bare `./scripts/classify-agent-existence.mjs` "not found" | Use the skill's absolute `<skill_dir>` in the `node` invocation |
| `agent-templates` → `400 MISSING_ARGUMENT: agentType` | The `agentType` query param is required — pass `AgentforceEmployeeAgent` |
| `agent-templates` returns empty `data[]` | Wrong `agentType` value — use `AgentforceEmployeeAgent`; empty results are not the same as "not provisioned" |
| Treating `activate`'s empty response as a failure | It's the documented success response (`EmptyRepresentation`) — verify via the Phase-7 SOQL instead of parsing this call's stdout |
| Tempted to token+curl for any of the three writes | Never — `sf api request rest --method POST --body @<file>` (or `--body '{}'`) handles auth for `/services/data/...` writes; token extraction is forbidden |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |