project-health_skill

Overview

This skill performs AI-agent readiness audits of project documentation and workflows to ensure future Claude Code sessions can understand, execute, and resume work reliably. It runs specialized checks for documentation clarity, literal executability of processes, and session handoff quality. Use it proactively before agent onboarding or handing a project to another AI session.

How this skill works

The skill uses three focused agents: context-auditor inspects docs for explicit, actionable language and complete examples; workflow-validator analyzes step sequences for discrete inputs/outputs, verification steps, and recovery paths; handoff-checker verifies session continuity artifacts like SESSION.md, phase tracking, and blockers. Each agent returns a score (0-100) plus concrete findings and remediation suggestions.

When to use it

• Before handing off a project to another Claude Code session
• When onboarding AI agents to contribute to a codebase
• After major refactors to confirm docs remain AI-executable
• When workflows fail because agents misinterpreted instructions
• As a periodic health check for AI-maintained projects

Best practices

• Write explicit file paths, commands, and expected outputs rather than vague references
• Split workflows into numbered, discrete steps with verification after each step
• Document environment prerequisites and exact success criteria up front
• Include recovery steps and failure modes for each action
• Maintain a SESSION.md with current phase, next actions, blockers, and decision rationale

Example use cases

• Run a full audit (all three agents) before ending a multi-session feature implementation
• Use context-auditor to convert human-friendly docs into AI-readable instructions
• Validate CI/CD or deployment workflows literal executability with workflow-validator
• Check session continuity and create a handoff checklist before shifting work to a new agent
• Re-audit after a refactor to catch missing verification or implicit assumptions