system-health

Detects drift between documented intent and actual filesystem state across the IL system.

Updated Apr 19, 2026
One-click install
npx skills add https://github.com/nickgogan/improvement-loop --skill system-health-nickgogan
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: system-health
Source: https://github.com/nickgogan/improvement-loop/tree/main/.claude/skills/system-health
Command: npx skills add https://github.com/nickgogan/improvement-loop --skill system-health-nickgogan

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Documentation and reality drift apart over time: CLAUDE.md says one skill count, agent definitions say another, and the filesystem shows a third. This Skill performs a quick read-only diagnostic that compares documented intent against observed state and produces a scannable drift report. ## Core Features & Use Cases - Skill Count Verification: Compares skill counts in CLAUDE.md, agent.md inventories, and actual SKILL.md files per agent role. - Agent & Governance Checks: Validates agent definitions, communication paths, source references, and governance translation freshness against source documents. - Structural & Recency Analysis: Checks fractal folder pattern compliance and reviews recent HISTORY.md and git log entries for unresolved issues. - Use Case: Before starting a major work session, run a quick health check to confirm skill counts, agent definitions, and governance docs are aligned, then get a prioritized list of recommended fixes. ## Quick Start Run a system health check with focus on all areas and report any drift between the documentation and the filesystem.

Frequently Asked Questions about system-health

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check if my documentation matches the actual file structure?▼

Run a drift detection check that compares documented counts and references in CLAUDE.md and agent definitions against actual files found via Glob and directory listings. The output is a table showing documented versus observed values with an aligned or drifted status per item.

What is the difference between system-health and system-audit?▼

System-health is a quick read-only diagnostic designed to complete in under two minutes, while system-audit is a comprehensive consistency audit. Use system-health for pre-flight checks and system-audit for deep verification.

Can system-health fix the drift it detects?▼

No, it is strictly read-only and only diagnoses drift. Fixes are handled by separate tools such as maintain-docs for documentation updates or translate-governance for governance alignment.

When should I not use a drift detection check?▼

Avoid it for full consistency audits, governance-specific alignment checks, or feedback processing, since dedicated skills cover those cases. It also ignores cosmetic issues like minor typos, focusing only on structural, count, and reference accuracy.

What focus areas can I check with the --focus argument?▼

The --focus argument accepts agents, skills, governance, structure, or all. Each focus narrows the diagnostic to that domain, with all being the default covering every check.