health-check

/health:check

Run a comprehensive diagnostic scan of your Claude Code environment. Identifies issues with plugin registry, settings files, hooks configuration, and MCP servers.

When to Use This Skill

Use this skill when...	Use another approach when...
Running comprehensive Claude Code diagnostics	Checking specific component only (use /health:plugins, /health:settings)
Troubleshooting general Claude Code issues	Plugin registry issues only (use /health:plugins --fix)
Validating environment configuration	Auditing plugins for project fit (use /health:audit)
Identifying misconfigured settings or hooks	Just viewing settings (use Read tool on settings.json)
Quick health check before starting work	Need agentic optimization audit (use /health:agentic-audit)

Context

• User home: !echo $HOME
• Current project: !pwd
• Project settings exists: !find .claude -maxdepth 1 -name 'settings.json'
• Local settings exists: !find .claude -maxdepth 1 -name 'settings.local.json'

Parameters

Parameter	Description
--fix	Attempt to automatically fix identified issues
--verbose	Show detailed diagnostic information

Execution

Execute this comprehensive health check by running the diagnostic scripts. Pass --verbose and --fix flags through from $ARGUMENTS when specified.

Step 1: Check plugin registry

bash "${CLAUDE_SKILL_DIR}/scripts/check-plugins.sh" --home-dir "$HOME" --project-dir "$(pwd)" [--fix] [--verbose]

Parse the STATUS= and ISSUES: lines from output.

Step 2: Validate settings files

bash "${CLAUDE_SKILL_DIR}/scripts/check-settings.sh" --home-dir "$HOME" --project-dir "$(pwd)" [--verbose]

Parse the STATUS= and ISSUES: lines from output.

Step 3: Check hooks configuration

bash "${CLAUDE_SKILL_DIR}/scripts/check-hooks.sh" --home-dir "$HOME" --project-dir "$(pwd)" [--verbose]

Parse the STATUS= and ISSUES: lines from output.

Step 4: Check MCP server configuration

bash "${CLAUDE_SKILL_DIR}/scripts/check-mcp.sh" --home-dir "$HOME" --project-dir "$(pwd)" [--verbose]

Parse the STATUS= and ISSUES: lines from output.

Step 5: Generate the diagnostic report

Using the structured output from Steps 1-4, print a diagnostic report following the template in REFERENCE.md. Include status indicators (OK/WARN/ERROR), issue counts, and recommended actions. If --fix was used and fixes were applied, include a summary of changes made.

Agentic Optimizations

Context	Command
Quick health check	/health:check
Health check with auto-fix	/health:check --fix
Detailed diagnostics	/health:check --verbose
Check plugin registry exists	test -f ~/.claude/plugins/installed_plugins.json && echo "exists" || echo "missing"
Validate settings JSON	jq empty .claude/settings.json 2>&1
List MCP servers	jq -r '.mcpServers | keys[]' .mcp.json 2>/dev/null

Known Issues Database

Reference these known Claude Code issues when diagnosing:

Issue	Symptoms	Solution
#14202	Plugin shows "installed" but not active in project	Run /health:plugins --fix
Orphaned projectPath	Plugin was installed for deleted project	Run /health:plugins --fix
Invalid JSON	Settings file won't load	Validate and fix JSON syntax
Hook timeout	Commands hang or fail silently	Check hook timeout settings

Flags

Flag	Description
--fix	Attempt automatic fixes for identified issues
--verbose	Include detailed diagnostic output

See Also

• /health:plugins - Detailed plugin registry diagnostics
• /health:settings - Settings file validation
• /health:hooks - Hooks configuration check
• /health:mcp - MCP server diagnostics