project-health

Project Health

One skill for everything about your project's Claude Code configuration. Run it at the start, middle, or end of a project — it figures out what's needed.

Goal: Zero permission prompts, well-organised context files, no cruft.

When to Use

Architecture: Sub-Agents

Heavy analysis runs in sub-agents to keep the main conversation clean. The main agent orchestrates; sub-agents do the scanning and return summaries.

Agent 1: Permission Auditor

Launched with Task(subagent_type: "general-purpose"). Prompt:

Read .claude/settings.local.json.

Agent 2: Context Auditor

Launched with Task(subagent_type: "general-purpose"). Prompt:

Parallel Execution

For a full health check, launch both agents in parallel:

Both return summaries. The main agent combines them into one report and proposes fixes.

Mode 1: Full Health Check

The default. Run this anytime.

Steps

1. Launch Permission Auditor and Context Auditor agents in parallel

2. Combine findings into a single report:

   ## Project Health Report
    
   **Project type**: [detected type]
   **CLAUDE.md quality**: [score]/100 ([grade])
    
   ### Permissions
   - Missing MCP servers: [list]
   - Leaked secrets: [count] found
   - Legacy syntax: [count] entries
   - Missing presets: [list]
    
   ### Context
   - Oversized files: [list]
   - Stale references: [list]
   - Missing docs: [list]
   - Overlaps: [list]
    
   ### Recommended Fixes
   1. [fix 1]
   2. [fix 2]
   ...

3. Apply fixes after single yes/no confirmation

Mode 2: New Project Setup

When: No .claude/settings.local.json exists, or user says "setup" / "kickoff".

Steps

1. Detect project type from files present:

   Indicator	Type	Preset
   wrangler.jsonc or wrangler.toml	cloudflare-worker	JS/TS + Cloudflare
   vercel.json or next.config.*	vercel-app	JS/TS + Vercel
   astro.config.*	astro	JS/TS + Static Sites
   package.json (no deploy target)	javascript-typescript	JS/TS
   pyproject.toml or setup.py or requirements.txt	python	Python
   Cargo.toml	rust	Rust
   go.mod	go	Go
   Gemfile or Rakefile	ruby	Ruby
   composer.json or wp-config.php	php	PHP
   pom.xml or build.gradle*	java	Java/JVM
   *.sln or *.csproj	dotnet	.NET
   mix.exs	elixir	Elixir
   Package.swift	swift	Swift + macOS
   pubspec.yaml	flutter	Mobile
   Dockerfile or docker-compose.yml	docker	Docker
   fly.toml or railway.json or netlify.toml	hosted-app	Hosting Platforms
   supabase/config.toml	supabase	Hosting + Database
   .claude/agents/ or operational scripts	ops-admin	—
   Empty directory	Ask the user	—

   Types stack (e.g. cloudflare-worker + javascript-typescript).

2. Generate .claude/settings.local.json:

   • Read references/permission-presets.md
   • Always include Universal Base (includes file access for .claude/**, //tmp/**)
   • Add detected language + deployment presets
   • Check if global ~/.claude/settings.local.json has home-relative file access patterns (~/Documents/**, ~/.claude/**). If not, suggest adding them there (NOT in the project file — home paths belong in global settings only)
   • Launch Permission Auditor agent to discover MCP servers and add per-server wildcards
   • Always include WebSearch, WebFetch
   • Always include explicit gh subcommands (workaround for Bash(gh *) bug)
   • Write with // comment groups

3. Generate CLAUDE.md:

   • Read references/templates.md
   • Use project-type-appropriate template

4. Generate .gitignore:

   • Read references/templates.md
   • Always include .claude/settings.local.json, .claude/plans/, .jez/screenshots/, .jez/artifacts/
   • Do NOT gitignore .jez/scripts/ — generated scripts are worth keeping

5. Optionally (ask first): git init + gh repo create

6. Warn: "Project settings.local.json SHADOWS global settings (does not merge). Session restart needed."

Mode 3: Tidy Permissions

When: User says "tidy permissions" or health check found permission issues.

Launch the Permission Auditor agent, then apply its recommended fixes.

Mode 4: Capture Learnings

When: End of session, "capture learnings", "save what we learned".

This runs in the main context (not a sub-agent) because it needs access to the conversation history.

1. Review conversation for discoveries worth preserving
2. Decide placement:

   Applies to all projects?
   ├── YES → ~/.claude/rules/<topic>.md
   └── NO  → Specific to a subdirectory?
       ├── YES → <dir>/CLAUDE.md
       └── NO  → Reference or operational?
           ├── Reference → docs/ or ARCHITECTURE.md
           └── Operational → ./CLAUDE.md (root)
3. Draft all changes as diffs in a single batch
4. Apply after single yes/no confirmation

Keep it concise: one line per concept.

Mode 5: Add Preset

When: "add python permissions", "add docker", "add MCP servers".

1. Read the preset from references/permission-presets.md
2. Read existing .claude/settings.local.json
3. Merge without duplicating
4. Remind: session restart required

Mode 6: Restructure Context

When: Root CLAUDE.md over 200 lines, "restructure memory".

1. Launch Context Auditor agent first
2. Based on findings:
   • Split oversized CLAUDE.md into .claude/rules/<topic>.md
   • Extract directory-specific content to sub-directory CLAUDE.md
   • Move reference material to docs/
   • Resolve overlaps
   • Create missing docs for project type
3. Present plan, apply after approval

Size Targets

Permission Syntax Quick Reference

What Does NOT Work

Important Behaviours

• Not hot-reloaded: settings.local.json edits need session restart
• "Don't ask again" injects at runtime (no restart) using colon format — normal
• Shadows, not merges: Project settings completely replace global
• gh bug: Bash(gh *) sometimes misses subcommands — include explicit Bash(gh issue *) etc.

Autonomy

• Just do it: Detect project type, launch audit agents, discover MCP servers
• Brief confirmation: Write/update files (single batch yes/no)
• Ask first: git init, GitHub repo, delete existing content, major restructures

Reference Files