aplaceforallmystuff/claude-ecosystem-health/ecosystem-health

Ecosystem Health

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

Check names for --check: vault-paths, skill-refs, mcp-servers, cli-tools, config-drift, staleness, orphans

Check Summary

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:

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