Detect drift between interconnected Claude Code components: skills, agents, MCP servers, vault paths, CLI tools, and configuration policies.
The problem: Complex Claude Code setups have dozens of skills, agents, and commands that reference each other by name, hardcode vault paths, and depend on MCP servers being configured. When something gets renamed, archived, or reconfigured, nothing detects the ripple effects. References break silently.
The solution: A single diagnostic skill that runs 7 checks across your entire Claude Code ecosystem and reports what's broken, stale, or misconfigured. Read-only by default.
| Check | Severity | What It Finds |
|---|---|---|
| Vault Path Validation | Critical | Hardcoded paths to files/directories that don't exist |
| Skill Cross-References | High | References to skills that were renamed or archived |
| MCP Server Health | Critical | MCP tool references with no configured server (phantom tools) |
| CLI Tool Availability | Medium | CLI tools referenced but not installed |
| Configuration Drift | High | Policy violations (e.g., using MCP when CLI is preferred) |
| Staleness Detection | Low | Skills/agents not modified in 90+ days |
| Orphan Detection | Low | Non-invocable skills with zero references (dead code) |
- Claude Code installed and configured
jqinstalled (for parsing.claude.json--brew install jqon macOS)- Skills/agents/commands in
~/.claude/directory structure
npx skills add aplaceforallmystuff/claude-ecosystem-healthgit clone https://github.com/aplaceforallmystuff/claude-ecosystem-health.git
cd claude-ecosystem-health
./install.shgit clone https://github.com/aplaceforallmystuff/claude-ecosystem-health.git
cp -r claude-ecosystem-health/skills/ecosystem-health ~/.claude/skills/git clone https://github.com/aplaceforallmystuff/claude-ecosystem-health.git ~/Dev/claude-ecosystem-health
ln -s ~/Dev/claude-ecosystem-health/skills/ecosystem-health ~/.claude/skills/ecosystem-healthclaude-ecosystem-health/
install.sh # Installer script
skills/
ecosystem-health/
SKILL.md # Main skill (lean, links to references)
references/
checks.md # Detailed check implementations (7 checks)
pitfalls.md # Lessons learned from production runs
The skill uses progressive disclosure: the main SKILL.md is concise and links to reference files for detailed check procedures and pitfalls. This keeps the skill lean for Claude's context window while preserving all the operational detail.
After installation, customize the skill for your environment. The files contain placeholder patterns that need updating:
- Vault paths (Check 1 in
references/checks.md) -- replace placeholder paths with your actual vault location - CLI tools (Check 4) -- add the CLI tools your setup depends on
- CLI-over-MCP policies (Check 5) -- define which MCP tools have CLI replacements in your setup
- Report output path -- set where health reports should be saved
- MCP server aliases (Check 3) -- list any proxy MCP servers (e.g., Docker-based servers that wrap multiple APIs)
# Full sweep (all 7 checks, monthly)
/ecosystem-health
# Quick check (checks 1-5, weekly)
/ecosystem-health --quick
# Single targeted check
/ecosystem-health --check vault-paths
/ecosystem-health --check skill-refs
/ecosystem-health --check mcp-servers
/ecosystem-health --check cli-tools
/ecosystem-health --check config-drift
/ecosystem-health --check staleness
/ecosystem-health --check orphansThe skill generates a structured markdown report with:
- Summary table (OK/Warning/Critical counts per check)
- Overall health rating (HEALTHY / NEEDS ATTENTION / DEGRADED)
- Detailed findings with affected files, line numbers, and remediation pointers
- Remediation summary table
| Status | Criteria |
|---|---|
| HEALTHY | 0 critical, 0-2 warnings |
| NEEDS ATTENTION | 0 critical, 3+ warnings OR 1 critical |
| DEGRADED | 2+ critical findings |
The skill is a structured prompt that guides Claude Code through 7 diagnostic checks. Each check:
- Scans source files (skills, agents, commands, hooks, CLAUDE.md)
- Extracts references and patterns
- Validates against the filesystem and configuration
- Classifies findings by severity
- Generates a report
No files are modified. The skill is read-only by design.
.claude.json can exceed 40k tokens in complex setups. MCP servers are configured at multiple levels:
- Top-level
mcpServers - Project-level
projects["/path"].mcpServers
The Read tool truncates large files, causing false positives (phantom servers that are actually configured at project level). jq extracts all server names regardless of file size.
This skill was battle-tested on a large production Claude Code setup. The first run surfaced genuine issues -- broken paths, phantom MCP tools, stale skill references -- alongside a handful of false positives that led to the jq approach for config parsing and the code-block filtering in model checks.
The references/pitfalls.md file documents every issue encountered during production use so you can avoid the same traps.
| Cadence | Mode | Use Case |
|---|---|---|
| Weekly | --quick |
Part of weekly review -- catches critical drift fast |
| Monthly | Full | First review of each month -- includes staleness and orphan checks |
| After changes | --check [name] |
After renaming, archiving, or reconfiguring anything |
| Debugging | --check [name] |
When something "used to work" but stopped |
Part of the aplaceforallmystuff skills collection:
- creation-guard — Prevent duplicate artifacts before creating new ones
- lessons-learned — Structured retrospectives that implement fixes
- rfu-audit — 11-gate utility validation before investing effort
This skill complements but doesn't replace:
- Inventory/sync tools — count and catalog everything (this skill validates health)
- MCP maintenance tools — manage individual servers (this skill detects which need attention)
- Upgrade tools — track Claude Code releases (this skill detects internal ecosystem drift)
MIT - see LICENSE