claude-ecosystem-health

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.

What It Catches

Requirements

• Claude Code installed and configured
• jq installed (for parsing .claude.json -- brew install jq on macOS)
• Skills/agents/commands in ~/.claude/ directory structure

Installation

Option 1: Skills CLI

npx skills add aplaceforallmystuff/claude-ecosystem-health

Option 2: Installer script

git clone https://github.com/aplaceforallmystuff/claude-ecosystem-health.git
cd claude-ecosystem-health
./install.sh

Option 3: Manual copy

git clone https://github.com/aplaceforallmystuff/claude-ecosystem-health.git
cp -r claude-ecosystem-health/skills/ecosystem-health ~/.claude/skills/

Option 4: Clone and symlink

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-health

Project Structure

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.

Setup

After installation, customize the skill for your environment. The files contain placeholder patterns that need updating:

1. Vault paths (Check 1 in references/checks.md) -- replace placeholder paths with your actual vault location
2. CLI tools (Check 4) -- add the CLI tools your setup depends on
3. CLI-over-MCP policies (Check 5) -- define which MCP tools have CLI replacements in your setup
4. Report output path -- set where health reports should be saved
5. MCP server aliases (Check 3) -- list any proxy MCP servers (e.g., Docker-based servers that wrap multiple APIs)

Usage

# 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 orphans

Output

The 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

Health Thresholds

How It Works

The skill is a structured prompt that guides Claude Code through 7 diagnostic checks. Each check:

1. Scans source files (skills, agents, commands, hooks, CLAUDE.md)
2. Extracts references and patterns
3. Validates against the filesystem and configuration
4. Classifies findings by severity
5. Generates a report

No files are modified. The skill is read-only by design.

Why jq Instead of Read?

.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.

Lessons from Production

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.

When to Run

Related Skills

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)

License

MIT - see LICENSE

Author

@aplaceforallmystuff