service-itsm-teams-debug
Debug and diagnose Microsoft Teams for Employee Service (ITSM) configuration failures — run a pass/fail validation checklist against the org and report exact remediation. Use this for: 'IT Desk login not working in Teams', 'UEL/CCP user can't log in to IT Service', 'Teams feature not showing / not enabled', 'CI Hub / Service Catalog / My Assets tab not loading', 'Teams Agentforce agent not responding', 'Teams swarming not working', 'Teams SSO failing', or any request to troubleshoot a Teams ITSM setup. Routes the problem to the right checklist (login, feature enablement, tab loading, Agentforce, swarming, SSO) and checks the exact CORS, External Client App, feature toggle, PSL, profile, auth-provider, named-credential, and messaging-channel settings each requires. DO NOT TRIGGER for first-time enablement (service-itsm-teams-configure / -itservice-configure / -itdesk-configure) or building the embedded agent from scratch (service-itsm-teams-employee-agent-configure).
- Installs
- 1.2K
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/forcedotcom/sf-skills --skill service-itsm-teams-debug- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads service-itsm-teams-debug automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Troubleshoot Microsoft Teams for Employee Service (ITSM)
When someone reports a Microsoft Teams for Employee Service failure — can't log in, a tab won't load, the feature isn't showing, the Agentforce agent won't reply, swarming or SSO is broken — this skill connects to the org, runs the pass/fail checklist for that specific problem, and reports each setting's actual value plus the exact Setup path to fix any that are wrong. It replaces "check every setting by hand" with a targeted, verified diagnosis.
Every read dispatches through headless-360 (dispatch_readonly for queries, dispatch only
for the optional swarming-token clear). No org password is needed.
Scope
- In scope: Diagnosing an already-attempted Teams ITSM setup that is failing. Routing the reported symptom to the right checklist and checking the exact settings it requires (CORS, External Client App, feature toggles, PSLs, profile session settings, auth provider, named credentials, messaging channel, Agentforce agent).
- Out of scope: First-time enablement (use
service-itsm-teams-configure/-itservice-configure/-itdesk-configure), building the embedded agent from scratch (useservice-itsm-teams-employee-agent-configure), and non-Teams Salesforce debugging.
Read-only by default. Every check is a
dispatch_readonlyquery — running the full checklist changes nothing. The only state-changing action is the optional swarming OAuth-token clear at the very end, and only with explicit user confirmation.
Step 1 — Identify the problem and collect inputs
Ask the user for their problem description if not already given. Match it to a checklist using
the Feature Map in references/configuration-checklists.md.
Some problems need extra inputs — ask for them up front:
| Problem type | Extra input to collect |
|---|---|
| Generic "login" (no app named) | Ask which app — IT Desk or IT Service |
| IT Desk login | End-user's Salesforce username (the person who can't log in) |
| IT Service login | CCP or UEL user?, then that end-user's Salesforce username |
| Agentforce not replying | Employee Experience Site URL |
| Swarming | End-user's username; Azure AD Tenant ID (optional — enables the Azure app check) |
| SSO | Azure AD Tenant ID (optional); optionally which app + end-user username |
Do not run the agent-specific checks until you have the mandatory inputs for that checklist
(e.g. don't skip asking for the end-user username on a login issue — the per-user checks are
MANUAL_CHECK_REQUIRED without it).
Step 2 — Route to the checklist
Pick the checklist from the Feature Map, then run its checks in order from
references/configuration-checklists.md:
| Symptom | Checklist |
|---|---|
| IT Desk login | LOGIN_DESK |
| IT Service login — UEL user | LOGIN_SERVICE_UEL |
| IT Service login — CCP user | LOGIN_SERVICE_CCP |
| Generic login (app unknown) | LOGIN (then ask which app) |
| Feature not showing / not enabled | MSTEAMS_CORE |
| Tab won't load (CI Hub, Service Catalog, Employee Enablement, My Assets) | TAB_LOADING |
| Lightning app not embedding / blank tab | LIGHTNING_OUT |
| Agentforce agent not replying | AGENTFORCE |
| Swarming | SWARMING |
| Single Sign-On | SSO (+ the app-specific login checklist if an app is named) |
When an app is named for an SSO issue, run both the SSO checklist and the matching login
checklist (LOGIN_DESK / LOGIN_SERVICE_CCP / LOGIN_SERVICE_UEL) — skip duplicate checks.
Step 3 — Run the checks
Execute each check's query via dispatch_readonly (queries and API fields are spelled out in the
reference). Record for each check: a status and the configured value actually read from
the org.
| Status | Render as | Meaning |
|---|---|---|
OK | OK | Correctly configured |
MISCONFIGURED / MISSING / DISABLED / ERROR | FAIL | Needs fixing — include the exact Setup path from the reference |
MANUAL_CHECK_REQUIRED | MANUAL | Needs manual verification (or a missing optional input like Tenant ID/username) — never render this as FAIL |
Step 4 — Report
Render a table with all four columns — #, Check, Status, Configured Value (never
omit the configured value), plus an Action Required note carrying the remediation for any
failed check. End with a one-line summary: N passed | N failed | N require manual verification.
- All passed: tell the user the Salesforce backend is correctly configured; if the problem persists, reload the Teams app (⋯ on the IT Desk/IT Service app → Reload app).
- Any failed: don't add the reload note — the per-check
Action Requiredsteps are the fix.
The full report-rendering rules, special-case notes, the example report layout, and the optional
swarming OAuth-token clear are in
references/report-generation.md.
Gotchas (verified)
| Issue | Detail |
|---|---|
The Teams ECA DeveloperName is ServiceCloudTeamsEca | The External Client App the login checks look for is ServiceCloudTeamsEca. (A per-org packaged instance may surface under a related name such as ServiceCloudMSTeamsEca; match on the ECA that backs the Teams login, and treat a missing app as "turn the feature off and on again.") |
| "Allow OAuth for employees" is Metadata-API-only for reading, and Setup-UI-only to change | Read via SOAP listMetadata(ProfileSessionSetting) → readMetadata on the fullName containing unified; field allowOauthForEmployees (true=enabled, false=disabled, absent=never configured). It is not on Profile describe and not REST/Tooling-queryable. To set it, use Setup → Profiles → (employee profile) → Session Settings. UEL users only. |
CORS check reads IsOauthCorsPolicyEnabled, allowed origins read CorsWhitelistEntry.UrlPattern | Both https://cdn.scs.static.lightning.force.com and https://teams.cloud.microsoft must be present. |
| Feature toggles are read via the FulfillerApp permissions Connect API | GET /connect/it-service/permissions/FulfillerApp returns the org/user feature flags; a FUNCTIONALITY_NOT_ENABLED error means the IServiceItsmTeamsFamily family is off at the org level. |
| Agentforce user-verification fields need SOAP v62+ | MessagingChannel.embeddedConfig (authMode, messagingAuthorizations.*) is silently omitted by SOAP v60 — use v62+. |
| Version prefix required | headless-360 dispatch/dispatch_readonly don't resolve API versions — always pass the full /services/data/vXX.0/... prefix. |
Related Skills
| Skill | When to use instead |
|---|---|
service-itsm-teams-configure | First-time enablement of the base Teams Go page toggle, Azure/Entra app, Named Credential, extension registration |
service-itsm-teams-itservice-configure | Completing the IT Service (employee) enablement checklist |
service-itsm-teams-itdesk-configure | Completing the IT Desk (fulfiller) enablement checklist + Swarming collaboration tool |
service-itsm-teams-employee-agent-configure | Building the embedded Agentforce agent from scratch so it replies in Teams |
service-itsm-channels-coordinate | Top-level menu across Teams, Slack, Swarming, Notifications, Portal |
FAQ
What does the service-itsm-teams-debug skill do?
Debug and diagnose Microsoft Teams for Employee Service (ITSM) configuration failures — run a pass/fail validation checklist against the org and report exact remediation. Use this for: 'IT Desk login not working in Teams', 'UEL/CCP user can't log in to IT Service', 'Teams feature not showing / not enabled', 'CI Hub / Service Catalog / My Assets tab not loading', 'Teams Agentforce agent not responding', 'Teams swarming not working', 'Teams SSO failing', or any request to troubleshoot a Teams ITSM setup. Routes the problem to the right checklist (login, feature enablement, tab loading, Agentforce, swarming, SSO) and checks the exact CORS, External Client App, feature toggle, PSL, profile, auth-provider, named-credential, and messaging-channel settings each requires. DO NOT TRIGGER for first-time enablement (service-itsm-teams-configure / -itservice-configure / -itdesk-configure) or building the embedded agent from scratch (service-itsm-teams-employee-agent-configure).
How do I install service-itsm-teams-debug?
Run npx skills add https://github.com/forcedotcom/sf-skills --skill service-itsm-teams-debug in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/service-itsm-teams-debug/ (personal) or .claude/skills/service-itsm-teams-debug/ (project).
Which AI agents can use service-itsm-teams-debug?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is service-itsm-teams-debug safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains service-itsm-teams-debug?
It is published by forcedotcom in forcedotcom/sf-skills. It has 1,162 recorded installs.
More from forcedotcom/sf-skills
platform-apex-generate
forcedotcom/sf-skills
Primary Apex authoring skill for class generation, refactoring, and review. ALWAYS ACTIVATE when the user mentions Apex, .cls, triggers, or asks to create/refactor a class (service, selector, domain, batch, queueable, schedulable, invocable, DTO, utility, interface, abstract, exception, REST resource). Use this skill for requests involving SObject CRUD, mapping collections, fetching related records, scheduled jobs, batch jobs, trigger design, @AuraEnabled controllers, @RestResource endpoints, custom REST APIs, or code review of existing Apex.
platform-apex-test-generate
forcedotcom/sf-skills
Use to generate and validate Apex test classes with TestDataFactory patterns, bulk testing (251+ records), mocking, assertions, and disciplined test-fix loops. Use when creating Apex test classes (for triggers, services, controllers, batch jobs, queueables, and callouts), improving coverage, debugging or fixing failing Apex tests, or running test/coverage analysis. Triggers on Test.cls files, sf apex run test, coverage reports. Do NOT trigger for production Apex (use platform-apex-generate) or Jest/LWC tests.
platform-apex-test-run
forcedotcom/sf-skills
Apex test execution, coverage analysis, and test-fix loops with 120-point scoring. Use when the user runs Apex tests, checks code coverage, fixes failing tests, or touches Test.cls / Test.cls files. DO NOT TRIGGER when writing Apex production code (use platform-apex-generate), Agentforce agent testing (use agentforce-test), or Jest/LWC tests (use experience-lwc-generate).
platform-apex-logs-debug
forcedotcom/sf-skills
Salesforce debug log analysis and troubleshooting with 100-point scoring. TRIGGER when: user analyzes debug logs, hits governor limits, reads stack traces, or touches .log files from Salesforce orgs. DO NOT TRIGGER when: running Apex tests (use platform-apex-test-run), generating or fixing Apex code (use platform-apex-generate), or Agentforce session tracing (use agentforce-observe).
platform-soql-query
forcedotcom/sf-skills
Use when the user needs SOQL/SOSL authoring or optimization: natural-language-to-query generation, relationship queries, aggregates, query-plan/selectivity analysis, and performance or safety improvements. TRIGGER when the user writes, optimizes, or debugs SOQL/SOSL, touches .soql files, or asks about relationship queries, aggregates, or query performance. DO NOT TRIGGER for bulk data operations (use platform-data-manage), Apex DML logic (use platform-apex-generate), or report/dashboard queries.
platform-metadata-deploy
forcedotcom/sf-skills
Salesforce DevOps automation using sf CLI v2. TRIGGER when: user deploys metadata, validates a deploy or does a dry-run, deploys to a Production org, quick-deploys a validated job ID, ships/promotes to prod, creates/manages scratch orgs or sandboxes, sets up CI/CD pipelines, or troubleshoots deployment errors with sf project deploy. DO NOT TRIGGER when: writing Apex code, building LWC components (use experience-lwc-generate), creating metadata definitions (use platform-custom-object-generate), deleting metadata from an org (use platform-destructive-deploy), or querying org data (use platform-data-manage).
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.