Detect drift between skills, agents, MCP servers, vault paths, and CLI tools.
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) |
# In Claude Code:
/plugin marketplace add aplaceforallmystuff/marketplace
/plugin install claude-ecosystem-health@aplaceforallmystuffManual install (without the marketplace)
git clone https://github.com/aplaceforallmystuff/claude-ecosystem-health.git
cp -r claude-ecosystem-health/skills/ecosystem-health ~/.claude/skills/Use it when:
- You want a monthly full sweep across your whole Claude Code setup.
- You want a fast weekly check as part of your weekly review.
- You have just renamed, archived, or reconfigured a skill, agent, or MCP server.
- Something "used to work" but stopped, and you need to find what broke.
- You want a targeted diagnosis of one area: vault paths, skill references, MCP servers, CLI tools, or config drift.
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.
claude-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.
Run a quick check as part of a weekly review:
# 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 writes a markdown report and prints a console summary. Illustrative output:
Ecosystem Health: NEEDS ATTENTION
Critical: 1 findings
Warnings: 3 findings
Info: 0 findings
Report saved to: ~/.claude/reports/ecosystem-health-report.md
The written report contains a summary table (OK/Warning/Critical counts per check), the overall health rating, detailed findings with affected files and line numbers, and a remediation summary table.
| Status | Criteria |
|---|---|
| HEALTHY | 0 critical, 0-2 warnings |
| NEEDS ATTENTION | 0 critical, 3+ warnings OR 1 critical |
| DEGRADED | 2+ critical findings |
- Claude Code installed and configured
jqinstalled (for parsing.claude.json--brew install jqon macOS)- Skills/agents/commands in
~/.claude/directory structure
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)
| 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 |
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.
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.