project-health

仓库: jezweb/claude-skills
安装量: 501
排名: #2126

安装

npx skills add https://github.com/jezweb/claude-skills --skill project-health

Status: Active Updated: 2026-01-30 Focus: Ensuring documentation and workflows are executable by AI agents

Overview

This skill evaluates project health from an AI-agent perspective - not just whether docs are well-written for humans, but whether future Claude Code sessions can:

  • Understand the documentation without ambiguity

  • Execute workflows by following instructions literally

  • Resume work effectively with proper context handoff

When to Use

  • Before handing off a project to another AI session

  • When onboarding AI agents to contribute to a codebase

  • After major refactors to ensure docs are still AI-executable

  • When workflows fail because agents "didn't understand"

  • Periodic health checks for AI-maintained projects

Agent Selection Guide

| "Will another Claude session understand this?" | context-auditor | Checks for ambiguous references, implicit knowledge, incomplete examples

| "Will this workflow actually execute?" | workflow-validator | Verifies steps are discrete, ordered, and include verification

| "Can a new session pick up where I left off?" | handoff-checker | Validates SESSION.md, phase tracking, context preservation

| Full project health audit | All three | Comprehensive AI-readiness assessment

Key Principles

1. Literal Interpretation

AI agents follow instructions literally. Documentation that works for humans (who fill in gaps) may fail for agents.

Human-friendly (ambiguous):

"Update the config file with your settings"

AI-friendly (explicit):

"Edit wrangler.jsonc and set account_id to your Cloudflare account ID (find it at dash.cloudflare.com → Overview → Account ID)"

2. Explicit Over Implicit

Never assume the agent knows:

  • Which file you mean

  • What "obvious" next steps are

  • Environment state or prerequisites

  • What success looks like

3. Verification at Every Step

Agents can't tell if something "feels right". Include verification:

  • Expected output after each command

  • How to check if a step succeeded

  • What to do if it failed

Agents

context-auditor

Purpose: Evaluate AI-readability of documentation

Checks:

  • Instructions use imperative verbs (actionable)

  • File paths are explicit (not "the config file")

  • Success criteria are measurable

  • No ambiguous references ("that thing", "as discussed")

  • Code examples are complete (not fragments)

  • Dependencies/prerequisites stated explicitly

  • Error handling documented

Output: AI-Readability Score (0-100) with specific issues

workflow-validator

Purpose: Verify processes are executable when followed literally

Checks:

  • Steps are discrete and ordered

  • Each step has clear input/output

  • No implicit knowledge required

  • Environment assumptions documented

  • Verification step after each action

  • Failure modes and recovery documented

  • No "obvious" steps omitted

Output: Executability Score (0-100) with step-by-step analysis

handoff-checker

Purpose: Ensure session continuity for multi-session work

Checks:

  • SESSION.md or equivalent exists

  • Current phase/status clear

  • Next actions documented

  • Blockers/decisions needed listed

  • Context for future sessions preserved

  • Git checkpoint pattern in use

  • Architecture decisions documented with rationale

Output: Handoff Quality Score (0-100) with continuity gaps

Templates

AI-Readable Documentation Template

See templates/AI_READABLE_DOC.md for a template that ensures AI-readability.

Key sections:

  • Prerequisites (explicit environment/state requirements)

  • Steps (numbered, discrete, with verification)

  • Expected Output (what success looks like)

  • Troubleshooting (common failures and fixes)

Handoff Checklist

See templates/HANDOFF_CHECKLIST.md for ensuring clean session handoffs.

Anti-Patterns

1. "See Above" References

# Bad
As mentioned above, configure the database.

# Good
Configure the database by running:
`npx wrangler d1 create my-db`

2. Implicit File Paths

# Bad
Update the config with your API key.

# Good
Add your API key to `.dev.vars`:

API_KEY=your-key-here

3. Missing Verification

# Bad
Run the migration.

# Good
Run the migration:
`npx wrangler d1 migrations apply my-db --local`

Verify with:
`npx wrangler d1 execute my-db --local --command "SELECT name FROM sqlite_master WHERE type='table'"`

Expected output: Should show your table names.

4. Assumed Context

# Bad
Now deploy (you know the drill).

# Good
Deploy to production:
`npx wrangler deploy`

Verify deployment at: https://your-worker.your-subdomain.workers.dev

Relationship to Other Tools

| project-docs-auditor | Traditional doc quality (links, freshness, structure) | Human readers

| project-health skill | AI-agent readiness (executability, clarity, handoff) | Claude sessions

| docs-workflow skill | Creating/managing specific doc files | Both

Quick Start

  • Full audit: "Run all project-health agents on this repo"

  • Check one aspect: "Use context-auditor to check AI-readability"

  • Before handoff: "Use handoff-checker before I end this session"

Success Metrics

A healthy project scores:

  • Context Auditor: 80+ (AI can understand without clarification)

  • Workflow Validator: 90+ (steps execute literally without failure)

  • Handoff Checker: 85+ (new session can resume immediately)

Projects below these thresholds have documentation debt that will slow future AI sessions.

← 返回排行榜