Detect drift between your interconnected Claude Code components: skills, agents, MCP servers, vault paths, CLI tools, and configuration policies. Read-only by default -- reports findings and points to existing tools for remediation.
When to Use
- Monthly full sweep (first weekly review of each month)
- Weekly quick check during weekly review
- After renaming, archiving, or reconfiguring any skill/agent/MCP server
- When something "used to work" but stopped
Modes
| Invocation | Checks Run | Use Case |
|---|---|---|
/ecosystem-health |
All 7 | Monthly full sweep |
/ecosystem-health --quick |
Checks 1-5 only (skip npm outdated in Check 3) | Weekly quick check |
/ecosystem-health --check [name] |
Single named check | Targeted diagnosis |
Check names for --check: vault-paths, skill-refs, mcp-servers, cli-tools, config-drift, staleness, orphans
Check Summary
| # | Check | Severity | Description |
|---|---|---|---|
| 1 | Vault Paths | CRITICAL | Hardcoded vault paths pointing to non-existent locations |
| 2 | Skill References | HIGH | References to renamed, archived, or missing skills |
| 3 | MCP Servers | CRITICAL | MCP tool references not matching configured servers |
| 4 | CLI Tools | MEDIUM | CLI tools referenced in CLAUDE.md not installed or broken |
| 5 | Config Drift | HIGH | Skills/agents violating stated CLAUDE.md policies |
| 6 | Staleness | LOW | Skills/agents not modified in 90+ days (full mode only) |
| 7 | Orphans | LOW | Non-invocable skills with zero references (full mode only) |
Detailed check implementations: See references/checks.md for full scan/validate/classify procedures.
Process
Step 0: Determine Mode
Parse the user's invocation:
- No arguments: Full mode (all 7 checks, npm outdated included)
--quick: Quick mode (checks 1-5, skip npm outdated)--check [name]: Single check mode (run only the named check)
Initialize counters for OK, Warning, Critical findings per check.
Step 1: Scan Source Files
Build the file lists that all checks will use:
# All active skill files (exclude _archive)
find ~/.claude/skills -name "SKILL.md" -not -path "*/_archive/*" -type f
# All agent files (top-level only)
ls ~/.claude/agents/*.md 2>/dev/null | grep -v _archive
# All command files
find ~/.claude/commands -name "*.md" -type f
# Hook scripts
cat ~/.claude/settings.json | python3 -c "
import json, sys
d = json.load(sys.stdin)
hooks = d.get('hooks', {})
for event, matchers in hooks.items():
for mg in matchers:
for h in mg.get('hooks', []):
print(h.get('command', ''))
"
# CLAUDE.md files
echo ~/.claude/CLAUDE.md
# Add your project-level CLAUDE.md paths here:
# echo ~/path/to/your/project/CLAUDE.md
Store all file paths for reuse across checks.
Step 2: Run Checks
Execute checks per the selected mode, following the detailed procedures in references/checks.md.
Output
Report File
Write report to a location in your project or system directory:
# Examples:
# ~/.claude/reports/ecosystem-health-report.md
# ~/your-vault/System/Ecosystem Health Report.md
Report Format
---
type: system-health
generated: [ISO 8601 timestamp]
mode: Full|Quick|Single ([check-name])
---
# Ecosystem Health Report
**Generated:** YYYY-MM-DD HH:MM | **Mode:** Full/Quick/Single
## Summary
| Category | OK | Warning | Critical |
|----------|-----|---------|----------|
| Vault Paths | X | X | X |
| Skill References | X | X | X |
| MCP Servers | X | X | X |
| CLI Tools | X | X | X |
| Config Drift | X | X | X |
| Staleness | X | X | X |
| Orphans | X | X | X |
| **Total** | **X** | **X** | **X** |
**Health:** HEALTHY / NEEDS ATTENTION / DEGRADED
Health thresholds:
- HEALTHY: 0 critical, 0-2 warnings
- NEEDS ATTENTION: 0 critical, 3+ warnings OR 1 critical
- DEGRADED: 2+ critical findings
Each finding includes: File, Line, Issue, Expected, Fix via.
Console Summary
After writing the report, display:
Ecosystem Health: [HEALTHY|NEEDS ATTENTION|DEGRADED]
Critical: N findings
Warnings: N findings
Info: N findings
Report saved to: [report path]
Remediation Guide
This skill is read-only. For fixes, use these tools:
| Issue Type | Fix Via |
|---|---|
| Broken vault paths | Manual edit of affected skill/agent |
| Wrong skill names | Manual edit of affected file |
| Phantom MCP tools | Manual edit to remove or replace with CLI |
| CLI-over-MCP policy violations | Manual edit to use CLI tool instead |
| Stale skills | Archive or manual review |
| Outdated MCP deps | Update per server |
| Orphaned skills | Review for archival |
Integration
Weekly Review
Use as part of your weekly review process:
- Weekly: Run
/ecosystem-health --quick(checks 1-5) - Monthly (first review of month): Run
/ecosystem-health(all 7 checks)
Daily Note (Optional)
After running, log a summary to today's daily note:
## Ecosystem Health Check
**Mode:** Quick/Full | **Health:** HEALTHY/NEEDS ATTENTION/DEGRADED
**Findings:** N critical, N warnings, N info
Pitfalls, Lessons Learned & Operational Notes
See references/pitfalls.md for detailed pitfalls from production runs and operational notes (config file size, MCP aliasing, CLI-over-MCP drift, vault path false positives, fuzzy matching, first-run expectations).