ecosystem-audit

Ecosystem Audit

A comprehensive audit of the entire ~/.claude/ ecosystem that scans 9 categories of persistent artifacts, scores each on a health scale, and produces an interactive HTML dashboard with prioritized cleanup recommendations.

When to Use

• User wants to know what skills are installed and which are actually used
• User wants to clean up their Claude Code environment
• User asks about ecosystem health, dormant artifacts, or storage bloat
• Monthly hygiene check (recommend running every 30 days)
• Before/after installing a batch of new skills
• When memory-hygiene or schliff:doctor findings suggest broader issues

Architecture

This skill orchestrates parallel subagents for speed. The audit runs in 3 phases:

Phase 1: Scan (parallel subagents)
  ├── Skills: parse JSONL logs for invocations, classify by domain
  ├── Memory: check all project dirs, apply memory-hygiene thresholds
  ├── Handoffs: count, classify lifecycle state, find orphans
  └── ADRs + Docs: read status fields, check links, classify

Phase 2: Score (sequential)
  ├── Calculate health % per category
  ├── Apply lifecycle scoring for worktrees
  ├── Cross-reference with memory-hygiene thresholds
  └── Generate prioritized recommendations (P0/P1/P2)

Phase 3: Report (write files)
  ├── Markdown summary → docs/handoffs/ecosystem_audit_report.md
  └── Interactive HTML → docs/handoffs/ecosystem_audit_report.html

Phase 1: Scan

Launch 4 parallel subagents, each responsible for one scan domain. Each subagent reports structured findings back to the orchestrator.

1A. Skill Usage Scan

Parse JSONL session logs to determine which skills are actually invoked.

Data source: ~/.claude/projects/<dir>/<uuid>.jsonl

What to extract:

• Lines where message.content[].name == "Skill" — these are invocations
• Extract input.skill (skill name), input.args, and timestamp
• Cross-reference with toolUseResult.commandName and toolUseResult.success

Classification rules:

• Active: invoked in the session log window (default: 30 days)
• Relevant-Dormant: not invoked but domain-aligned with user's work (check user profile in memory files for role/domain context)
• Niche-Dormant: specialized domain unlikely to be needed (bio/chem databases, quantum computing, wet-lab integrations, astrophysics, game dev, embedded systems)
• DevOps-Dormant: IaC/CI/CD tools (terraform, helm, k8s, ansible, dockerfile, jenkins, github-actions generators and validators)
• Not-a-Skill: workspace directories, cloned repos, .DS_Store, README files
• Deprecated: SKILL.md explicitly says "DEPRECATED" or "merged into"