Project Health

What Is Project Health?

Project Health is a Claude Code skill designed for comprehensive project configuration and health management. Acting as an all-in-one assistant, it helps set up new projects, audit existing ones, tidy up accumulated cruft, and manage permissions and documentation with minimal friction. With smart automation and the use of sub-agents for heavy analysis, Project Health keeps your project’s configuration files clean, permissions correctly set, and project knowledge well-organized—right from project kickoff to completion.

Why Use Project Health?

Managing project configuration, permissions, and documentation is often a tedious, error-prone, and fragmented process. Teams and individuals alike can struggle with:

• Inconsistent or missing configuration files
• Leaked secrets in version control
• Stale or outdated documentation
• Unclear permission settings
• Accumulated "cruft" (unnecessary files or settings)
• Manual context management that slows development

Project Health addresses these pain points by automating the setup and maintenance of essential files (settings.local.json, CLAUDE.md, .gitignore, and more), auditing your project for potential issues, and providing easy commands for common tasks. The end goal is a well-organized, secure, and maintainable codebase with zero permission prompts and clear context files.

How to Get Started

Project Health is available as a Claude Code skill and can be integrated into your workflow through simple trigger commands. Here’s how you can use it:

1. Install the Skill:
   Clone or reference the skill from the Project Health GitHub repository.

2. Trigger the Skill:
   Use natural language commands to invoke the desired function. Example triggers include:

   • "project health"
   • "setup project"
   • "tidy permissions"
   • "capture learnings"
   • "audit context"
   • "add python permissions"

3. Follow Prompts:
   The skill guides you through the process, setting up or auditing files as needed. For heavy analysis (e.g., permission audits or secret scanning), it uses sub-agents to keep the main session context clean.

Example: Initial Project Setup

## In your Claude Code environment
setup project
## or
kickoff

This command will generate the foundational configuration files:

• settings.local.json
• CLAUDE.md
• .gitignore

Example: Auditing an Existing Project

## To perform a comprehensive audit
project health

## To focus on context files only
audit context

Key Features

1. Automated Project Initialization

On a new project, Project Health creates:

• settings.local.json: Local configuration tailored for your environment.
• CLAUDE.md: Project documentation starter, capturing intent and discoveries.
• .gitignore: Standard ignore patterns to keep your repository clean.

Example: Generated .gitignore

## Python
__pycache__/
*.pyc

## VSCode
.vscode/

## Local settings
settings.local.json

2. Comprehensive Project Audits

Run "project health" or "check project" at any time to scan for:

• Incorrect or missing permissions
• Context file quality
• MCP (Memory, Context, Permissions) coverage
• Leaked secrets or sensitive data
• Stale documentation

3. Permission and Settings Management

Tidy permission files with commands like "tidy permissions" or "clean settings". You can also add presets with simple commands:

add python permissions
add docker permissions

This updates your settings.local.json with relevant permission entries, ensuring Claude Code can function securely and effectively.

Example: Adding Python Permissions

{
  "permissions": {
    "python": {
      "enabled": true,
      "allowedPaths": ["src/", "scripts/"]
    }
  }
}

4. Documentation and Learning Capture

Keep your CLAUDE.md up-to-date by capturing session learnings:

capture learnings
update CLAUDE.md

Project Health will prompt you for discoveries, lessons learned, or architectural decisions from the session and append them to your documentation.

5. Context and Memory Auditing

With "audit context" or "audit memory", Project Health reviews your context files for quality, coverage, and relevance, helping prevent context bloat and outdated references.

6. Sub-Agent Architecture

Heavy or potentially disruptive analysis (like secret scanning) is handled by sub-agents. This design keeps the main session context clean, prevents memory overload, and improves responsiveness.

Best Practices

• Run at Project Start and End: Use "setup project" at the beginning and "project health" before delivery or handoff to ensure everything is in order.
• Audit Regularly: Schedule periodic audits, especially on shared or long-running projects, to catch permission drifts and documentation gaps early.
• Capture Learnings Frequently: After major sessions or retrospectives, run "capture learnings" to keep documentation living and useful.
• Tidy Permissions on Change: Whenever you add new dependencies or integrations, update permissions using the relevant commands.

Important Notes

• Claude Code Only: Project Health is compatible exclusively with Claude Code environments.
• File Overwrites: When initializing or tidying settings, existing files may be overwritten. Ensure you have backups or version control.
• Sensitive Data Handling: While Project Health audits for leaked secrets, always review and validate results before pushing changes to public repositories.
• Customization: Default presets (for permissions or .gitignore) may need adjustment for unique project requirements—review generated files before use.
• Community Contributions: As an open-source skill, improvements and new permission presets are welcome via the GitHub repository.