Skip to main content
hc
Submit
skillsSource-backedReview first Safety ✓ Privacy ✓

Claude Code Troubleshooting Triage Capability Pack Skill

Expert Claude Code troubleshooting triage capability pack for diagnosing install failures, auth errors, MCP issues, sandbox blocks, and update regressions with source-backed triage matrices and privacy-safe support output.

by kiannidev·added 2026-06-15·
Claude CodeCodexWindsurfGeminiCursorCLI
HarnessClaude CodeCodexWindsurfGeminiCursorCLI
Level:expertType:capability-packVerified:validated
Review first — review before installing

Open the source and read safety notes before installing.

Safety notes

  • This skill triages failures; it must not disable sandbox, security, or managed policy without explicit admin approval.
  • Do not paste secrets, OAuth tokens, or session cookies into public troubleshooting threads.
  • Avoid running destructive fix steps (global uninstall, credential deletion) without user confirmation.
  • MCP and plugin removals can break team workflows; document rollback before changes.

Privacy notes

  • Troubleshooting logs can expose repo paths, auth emails, internal URLs, and MCP tool arguments.
  • Support handoffs may include session transcripts; redact customer or employee identifiers first.
  • Network proxy and ZDR settings can reveal enterprise security posture; keep details in private channels.
  • Diagnostic exports may contain API usage metadata governed by org retention policies.

Prerequisites

  • Claude Code version, OS, install method, and recent config or update changes.
  • Access to local logs, settings files, and MCP configuration relevant to the failure.
  • Ability to reproduce the failure in a controlled session when safe.
  • Admin contact path for managed policy, network proxy, or enterprise auth issues.

Schema details

Install type
package
Reading time
9 min
Difficulty score
79
Troubleshooting
Yes
Breaking changes
No
Source repository stats
Scope
Source repo
Package metadata
Skill and platform metadata
Skill type
capability-pack
Skill level
expert
Verification
validated
Verified at
2026-06-15
Retrieval sources
https://code.claude.com/docs/en/troubleshootinghttps://code.claude.com/docs/en/mcphttps://code.claude.com/docs/en/sandboxinghttps://code.claude.com/docs/en/securityhttps://code.claude.com/docs/en/settingshttps://github.com/anthropics/claude-codehttps://developers.google.com/search/docs/fundamentals/creating-helpful-content
Tested platforms
ClaudeClaude CodeCodexCursorWindsurfGeneric AGENTS
PlatformSupportInstall path
claude-codeNative.claude/skills/<skill-name>/SKILL.md
codexNative.agents/skills/<skill-name>/SKILL.md
windsurfNative.windsurf/skills/<skill-name>/SKILL.md
geminiNative.gemini/skills/<skill-name>/SKILL.md or .agents/skills/<skill-name>/SKILL.md
cursorAdapter.cursor/rules/<skill-name>.mdc
cliManualAGENTS.md or tool-specific context file
Full copyable content
# Trigger
"Apply the Claude Code troubleshooting triage capability pack for this incident."

# Required output
1) Symptom classification and affected surface
2) First-pass diagnostic checklist results
3) Likely root cause with evidence links
4) Fix steps and rollback options
5) Privacy-safe summary for user or admin handoff

About this resource

Knowledge Freshness

This capability pack is grounded in Claude Code troubleshooting, MCP, sandboxing, security, and settings documentation verified on 2026-06-15. Error messages and defaults change with releases; prefer live docs and changelog notes.

Retrieval Sources

Source Verification Notes

Verified against public Claude Code troubleshooting and integration docs on 2026-06-15:

  • Official troubleshooting docs cover install paths, auth, updates, MCP, and common environment conflicts with linked fix steps.
  • MCP and sandbox docs explain permission prompts, managed policy overrides, and isolation failures that mimic generic app errors.
  • Settings documentation maps user, project, and managed layers that affect triage order.

Scope Note

This pack triages Claude Code operational failures for champions, admins, and support workflows. It is distinct from incident timeline reconstruction skills focused on production outages outside Claude Code.

Core Workflow

  1. Capture symptom, Claude Code version, OS, install channel, and recent changes.
  2. Classify failure surface: auth, network, MCP, sandbox, plugin, update, or project config.
  3. Run first-pass checks from official troubleshooting docs for that surface.
  4. Collect minimal logs and settings evidence without exposing secrets.
  5. Identify likely root cause and alternative hypotheses with confidence notes.
  6. Propose fix steps, rollback options, and admin escalation triggers.
  7. Deliver privacy-safe summary for user or internal handoff.

Capability Scope

  • Symptom classification by Claude Code surface.
  • First-pass diagnostic checklists from official docs.
  • MCP, sandbox, and settings drift detection.
  • Fix and rollback planning with escalation paths.
  • Privacy-safe support handoff summaries.

Compatibility

Native

  • Claude Code / Claude: use as an Agent Skill during internal support or champion office hours for Claude Code failures.

Manual Adaptation

  • Codex, Cursor, Windsurf, Generic AGENTS: apply the triage checklist when supporting Claude Code deployments using public documentation.

Required Inputs

  • Error messages, timestamps, and reproduction steps.
  • Claude Code version and installation method.
  • Relevant settings, MCP configs, and recent update or policy changes.
  • Network, proxy, or managed policy context for enterprise users.

Production Rules

  • Start with official troubleshooting doc steps before experimental fixes.
  • Prefer reversible changes; document rollback for MCP and plugin edits.
  • Escalate to admins when managed policy or ZDR blocks the fix path.
  • Never share live tokens or session exports in public channels.
  • Label unverified hypotheses clearly in handoff notes.
  • Close triage with explicit next owner and verification step.

Review Matrix

Topic Signal Action
Auth OAuth or SSO loop Check clock, redirect, managed auth policy
MCP Tool timeout Verify server, OAuth token, allowlist
Sandbox Write blocked Review allowWrite and managed overrides
Update Post-upgrade regression Compare version with changelog breaking notes
Network Proxy errors Validate enterprise proxy and DNS settings
Config Project vs user drift Align settings layers and document override

Output Contract

  1. Symptom classification and affected surface.
  2. Diagnostic checklist results with evidence.
  3. Likely root cause and alternatives.
  4. Fix steps, rollback, and escalation path.
  5. Privacy-safe handoff summary.

Troubleshooting

Issue: Official doc step does not match local UI Fix: Confirm Claude Code channel/version; check changelog for renamed settings.

Issue: MCP works locally but fails for one user Fix: Compare user OAuth tokens, managed MCP allowlist, and project .mcp.json scope.

Issue: Sandbox errors after policy update Fix: Diff managed policy JSON against last known good; reproduce in staging project.

Issue: Intermittent network failures only on VPN Fix: Document proxy exceptions required by troubleshooting docs; escalate to IT.

Duplicate Check

Checked content/skills/, content/guides/, open PRs, and the live catalog for Claude Code troubleshooting workflows. Official troubleshooting docs exist, but no skills entry provides this reusable triage capability pack with review matrix and output contract.

Editorial Disclosure

Submitted as an independent source-backed HeyClaude content entry by kiannidev. It is based on public Claude Code documentation and the public Anthropic claude-code repository. No paid placement, referral link, affiliate link, or vendor sponsorship is used.

#claude-code#troubleshooting#support#mcp#capability-pack

Source citations

Add this badge to your README

Show that Claude Code Troubleshooting Triage Capability Pack Skill is listed on HeyClaude. Paste this Markdown into your README — it renders the badge and links back to this page.

Listed on HeyClaude
[![Listed on HeyClaude](https://heyclau.de/badge/skills/claude-code-troubleshooting-triage-capability-pack.svg)](https://heyclau.de/entry/skills/claude-code-troubleshooting-triage-capability-pack)

How it compares

Claude Code Troubleshooting Triage Capability Pack Skill side by side with 3 alternatives on trust, install, platform support, and disclosed safety notes — all from reviewed registry metadata.

FieldClaude Code Troubleshooting Triage Capability Pack Skill

Expert Claude Code troubleshooting triage capability pack for diagnosing install failures, auth errors, MCP issues, sandbox blocks, and update regressions with source-backed triage matrices and privacy-safe support output.

Open dossier 		Claude Agent SDK MCP Integration Capability Pack Skill

Expert Claude Agent SDK MCP integration capability pack for designing, reviewing, and rolling out Agent SDK MCP integration with source-backed checklists, production rules, and privacy-safe output contracts.

Open dossier 		Claude Code GitLab CI agent Capability Pack Skill

Expert Claude Code GitLab CI agent capability pack for designing, reviewing, and rolling out GitLab CI agent with source-backed checklists, production rules, and privacy-safe output contracts.

Open dossier 		Claude Code managed MCP governance Capability Pack Skill

Expert Claude Code managed MCP governance capability pack for designing, reviewing, and rolling out managed MCP governance with source-backed checklists, production rules, and privacy-safe output contracts.

Open dossier
Trust
Install riskReview firstReview firstReview firstReview first
Notes Safety ✓ Privacy ✓ Safety ✓ Privacy ✓ Safety ✓ Privacy ✓ Safety ✓ Privacy ✓
Categoryskillsskillsskillsskills
Sourcesource-backedsource-backedsource-backedsource-backed
Authorkiannidevkiannidevkiannidevkiannidev
Added2026-06-152026-06-142026-06-142026-06-14
Platforms
Claude CodeCodexWindsurfGeminiCursorCLI
Claude CodeCodexWindsurfGeminiCursorCLI
Claude CodeCodexWindsurfGeminiCursorCLI
Claude CodeCodexWindsurfGeminiCursorCLI
Source repo————
Safety notes✓This skill triages failures; it must not disable sandbox, security, or managed policy without explicit admin approval. Do not paste secrets, OAuth tokens, or session cookies into public troubleshooting threads. Avoid running destructive fix steps (global uninstall, credential deletion) without user confirmation. MCP and plugin removals can break team workflows; document rollback before changes.✓This skill plans Agent SDK MCP integration; it must not execute destructive changes without explicit approval. Browser, computer-use, and remote surfaces can access sensitive UI state; scope tests carefully. MCP and SDK integrations may exfiltrate data if tool scopes are too broad. The public `anthropics/claude-code` repository ships documentation links to code.claude.com for settings, security, and integration surfaces. Scheduled or autonomous workflows compound risk; cap blast radius in staging first.✓This skill plans GitLab CI agent; it must not execute destructive changes without explicit approval. Browser, computer-use, and remote surfaces can access sensitive UI state; scope tests carefully. MCP and SDK integrations may exfiltrate data if tool scopes are too broad. The public `anthropics/claude-code` repository ships documentation links to code.claude.com for settings, security, and integration surfaces. Scheduled or autonomous workflows compound risk; cap blast radius in staging first.✓This skill plans managed MCP governance; it must not execute destructive changes without explicit approval. Browser, computer-use, and remote surfaces can access sensitive UI state; scope tests carefully. MCP and SDK integrations may exfiltrate data if tool scopes are too broad. The public `anthropics/claude-code` repository ships documentation links to code.claude.com for settings, security, and integration surfaces. Scheduled or autonomous workflows compound risk; cap blast radius in staging first.
Privacy notes✓Troubleshooting logs can expose repo paths, auth emails, internal URLs, and MCP tool arguments. Support handoffs may include session transcripts; redact customer or employee identifiers first. Network proxy and ZDR settings can reveal enterprise security posture; keep details in private channels. Diagnostic exports may contain API usage metadata governed by org retention policies.✓Reviews may expose integration tokens, customer metadata, and internal URLs related to Agent SDK MCP integration. Telemetry and analytics configs can include account emails; redact before sharing externally. Keep troubleshooting logs in internal channels unless explicitly sanitized. Third-party vendors remain outside Anthropic retention policies; document separately.✓Reviews may expose integration tokens, customer metadata, and internal URLs related to GitLab CI agent. Telemetry and analytics configs can include account emails; redact before sharing externally. Keep troubleshooting logs in internal channels unless explicitly sanitized. Third-party vendors remain outside Anthropic retention policies; document separately.✓Reviews may expose integration tokens, customer metadata, and internal URLs related to managed MCP governance. Telemetry and analytics configs can include account emails; redact before sharing externally. Keep troubleshooting logs in internal channels unless explicitly sanitized. Third-party vendors remain outside Anthropic retention policies; document separately.
Prerequisites
  • Claude Code version, OS, install method, and recent config or update changes.
  • Access to local logs, settings files, and MCP configuration relevant to the failure.
  • Ability to reproduce the failure in a controlled session when safe.
  • Admin contact path for managed policy, network proxy, or enterprise auth issues.
  • Access to Claude Code or Agent SDK environment where Agent SDK MCP integration will run.
  • Ability to read project, user, and managed settings relevant to the workflow.
  • Staging repository or sandbox account for safe validation.
  • Platform or security stakeholder available for policy-bound rollouts.
  • Access to Claude Code or Agent SDK environment where GitLab CI agent will run.
  • Ability to read project, user, and managed settings relevant to the workflow.
  • Staging repository or sandbox account for safe validation.
  • Platform or security stakeholder available for policy-bound rollouts.
  • Access to Claude Code or Agent SDK environment where managed MCP governance will run.
  • Ability to read project, user, and managed settings relevant to the workflow.
  • Staging repository or sandbox account for safe validation.
  • Platform or security stakeholder available for policy-bound rollouts.
Install————
Config————
Citations
ClaimUnclaimedUnclaimedUnclaimedUnclaimed

Signals

Loading live community signals…

More like this, weekly

A short, calm digest of reviewed Claude resources. Unsubscribe any time.