--- name: project-audit description: Run a comprehensive audit on any Claude Code project. Scores 10 categories from 0-10 (total /100), identifies gaps, and generates a prioritized fix kit with copy-pasteable solutions. Use when you want to evaluate and improve your Claude Code setup, developer experience, security posture, or project quality. --- # Elite Project Audit Skill ## Purpose Audit any Claude Code project across 10 categories. Produce a score out of 100, identify gaps, and generate a prioritized fix kit with actionable solutions. Elite performance comes from elite structure. This audit shows you where the structure is missing. ## How to Run When this skill is invoked, execute the full audit below. Read the actual project files — don't guess or assume. Every score must be evidence-based. **Output format:** Write the full audit report to `docs/audit-report.md` with: 1. Score summary table (all 10 categories) 2. Detailed findings per category (what exists, what's missing, evidence) 3. Prioritized fix kit (ordered by impact-to-effort ratio) 4. Top 3 quick wins (things fixable in under 15 minutes) --- ## Category 1: CLAUDE.md Quality (0-10) CLAUDE.md is the highest-leverage file in any Claude Code project. It loads every session and shapes every response. **What to check:** - Does `CLAUDE.md` exist at the project root? - Does it follow the WHAT / WHY / HOW framework? - WHAT: Tech stack, project structure, key files - WHY: Project purpose, what each part does - HOW: Build commands, test commands, conventions, how to verify changes - Is it lean? (Under ~150 instructions. Claude Code's system prompt already contains ~50 instructions — bloated CLAUDE.md files cause instruction-following to degrade) - Does it include common mistakes to avoid? (The highest-value section — only include things Claude gets wrong) - Are critical rules emphasized with "IMPORTANT:" or "NEVER"? - Does it avoid duplicating information available in skills or other docs? - Are build/test/lint commands documented? - Is there a clear git workflow defined? **Scoring guide:** - 0-2: Missing or just a project description with no actionable instructions - 3-4: Exists but bloated, unstructured, or missing key sections - 5-6: Covers basics but missing conventions, common mistakes, or emphasis on critical rules - 7-8: Well-structured, lean, covers WHAT/WHY/HOW with clear conventions - 9-10: Tight, battle-tested, every line earns its place, iterated based on real mistakes **Also check for:** - `CLAUDE.local.md` for personal overrides (should be in .gitignore) - `~/.claude/CLAUDE.md` for global preferences - Subdirectory CLAUDE.md files in monorepos --- ## Category 2: Skills & Commands (0-10) Skills provide on-demand context that loads only when relevant. Commands are reusable prompt templates. Together they prevent re-explaining standards every session and save significant tokens. **What to check:** *Skills (`.claude/skills/`):* - Do any project-specific skills exist? - Does each skill have a clear `SKILL.md` with a descriptive name and trigger description? - Are skills focused on a single domain? (design system, API patterns, database migrations, etc.) - Do skills reference actual project files rather than generic advice? - Is domain knowledge moved OUT of CLAUDE.md and INTO skills? (key for token efficiency) *Commands (`.claude/commands/`):* - Do any slash commands exist? - Essential commands to look for: - Session start / catchup (review branch status, errors) - Pre-deploy check (lint, typecheck, build, test, security scan) - PR creation (cleanup, commit, push, create PR) - Planning (create implementation plan before coding) - Test generation (scaffold tests for existing code) **Scoring guide:** - 0-2: No skills or commands configured - 3-4: 1-2 basic commands, no skills - 5-6: Some commands exist but no skills, or skills exist but are generic - 7-8: 3+ skills with clear triggers, 4+ commands covering key workflows - 9-10: Comprehensive skill + command library tailored to the project, with supporting reference files --- ## Category 3: Hooks Configuration (0-10) Hooks are deterministic guardrails — unlike CLAUDE.md rules (which are advisory), hooks are guaranteed to execute. They are your safety net. **What to check:** - Read `.claude/settings.json` (or equivalent) for hook configuration - Essential hooks to look for: | Hook | Event | Purpose | |------|-------|---------| | Auto-format | PostToolUse (Write/Edit) | Runs formatter (Prettier, Biome, etc.) on every file Claude edits | | Safety guard | PreToolUse (Bash) | Blocks dangerous commands: rm -rf, DROP TABLE, DROP DATABASE, DELETE FROM...WHERE 1, git push --force | | Notification | Notification | Desktop alert when Claude needs attention | | Lint check | PostToolUse (Write/Edit) | Runs linter after edits (optional, can be noisy) | | Pre-compact | PreCompact | Preserves critical context before compaction | **Scoring guide:** - 0-2: No hooks configured - 3-4: One hook (usually auto-format) - 5-6: Auto-format + one other hook - 7-8: Auto-format + safety guard + notification - 9-10: All three essential hooks plus project-specific hooks (e.g., migration file protection, test runner) --- ## Category 4: MCP Servers (0-10) MCP servers connect Claude Code to external tools and services. The right MCPs eliminate context-switching. Too many bloat startup time and context. **What to check:** - Run `claude mcp list` or check `.claude/settings.json` for MCP configuration - Evaluate based on project stack: | Stack Component | Recommended MCP | |----------------|----------------| | GitHub repos | GitHub MCP | | Supabase / Postgres | Supabase MCP or PostgreSQL MCP | | Library docs needed | Context7 | | Browser testing needed | Playwright MCP | | Figma designs | Figma MCP | | Slack communication | Slack MCP | | Project management | Linear / Notion MCP | | Web scraping needed | Firecrawl MCP | **Scoring guide:** - 0-2: No MCP servers configured - 3-4: 1 MCP that's not critical to the workflow - 5-6: 1-2 relevant MCPs for the stack - 7-8: 2-3 well-chosen MCPs matching the primary workflow - 9-10: Right MCPs for the stack, not overloaded, wildcard permissions configured for trusted servers **Important:** More is NOT better. Score DOWN if there are 5+ MCPs that bloat context without clear value. --- ## Category 5: Project Structure (0-10) Clean project structure helps both humans and Claude navigate the codebase efficiently. **What to check:** - Scan for files over 500 lines (flag any over 300 as warnings) - Check for clear directory organization (components, lib, utils, hooks, types separated) - Look for barrel exports / index files where appropriate - Check for code duplication across files - Monorepo: packages clearly separated with their own configs - Are there any "junk drawer" directories? (utils/ with 30 unrelated files) - Is there a clear separation between UI, business logic, API, and configuration layers? **Scoring guide:** - 0-2: No clear structure, files scattered, large monolithic files - 3-4: Basic structure but multiple files over 500 lines, unclear separation - 5-6: Good directory structure but some large files or unclear boundaries - 7-8: Clean separation, most files under 300 lines, clear naming - 9-10: Well-organized, modular, every directory has a clear purpose, no file over 500 lines --- ## Category 6: Security (0-10) Security basics that should be in place before any production deployment. Score based on what is actually implemented, not what is planned. **What to check:** *Authentication & Authorization:* - Are all API routes behind authentication? (check for unprotected endpoints) - Is there role-based access control where needed? - Are auth tokens validated on every request? *Data Protection:* - Database: Is Row Level Security (RLS) enabled? (Supabase/Postgres) - Are environment variables used for ALL secrets? (check for hardcoded keys) - Is `.env` in `.gitignore`? - Does `.env.example` exist with placeholder values? - Is PII excluded from server logs? *Input Validation:* - Are request bodies validated? (Zod, Joi, or equivalent) - Is there SQL injection prevention? (ORM or parameterized queries) - Is there XSS prevention? (output encoding, sanitization) *Headers & Configuration:* - Check for security headers: Content-Security-Policy, X-Frame-Options, X-Content-Type-Options - Is CORS configured (not wildcard * in production)? - Are rate limits on API routes? (especially auth, payment, and AI endpoints) *Dependencies:* - Run npm audit / pnpm audit / yarn audit and check severity - Are there known critical vulnerabilities? **Scoring guide:** - 0-2: Major gaps — no auth on routes, no RLS, hardcoded secrets - 3-4: Auth exists but inconsistent, secrets in env but some gaps - 5-6: Auth on most routes, RLS enabled, env vars used, but missing validation or headers - 7-8: Solid auth, RLS, validation, env management, basic security headers - 9-10: Comprehensive — auth + RLS + validation + headers + rate limiting + clean audit + no PII in logs --- ## Category 7: Testing (0-10) Not about 100% coverage. About whether the paths that matter are tested. **What to check:** *Infrastructure:* - Is a test runner configured? (Vitest, Jest, Mocha, etc.) - Is there a test setup file with proper mocks? - Can tests run with a single command? - Are tests in the CI/CD pipeline? *Coverage of critical paths:* - Authentication flows (login, signup, token refresh, logout) - Payment / billing webhooks (if applicable) - Core API routes (the ones that handle user data) - Input validation (do bad inputs get rejected?) - Business logic (state machines, calculations, transformations) - Data integrity (deduplication, idempotency) *E2E tests:* - Is Playwright / Cypress configured? - Are there E2E tests for critical user flows? **Scoring guide:** - 0-2: No test runner or tests - 3-4: Test runner configured, 1-5 test files, minimal coverage - 5-6: Test infrastructure solid, critical auth and API paths tested, in CI - 7-8: Good unit + integration coverage of critical paths, E2E for core flows - 9-10: Comprehensive testing, E2E for all critical flows, edge cases covered, tests run in CI with coverage thresholds **How to count:** List the total number of API routes and the number with tests. Below 30% coverage = score capped at 5. --- ## Category 8: Git & CI/CD (0-10) Version control hygiene and automated quality gates. **What to check:** *Git practices:* - Is there a clear branching strategy? (feature branches from main) - Are commits following a convention? (conventional commits: feat/, fix/, etc.) - Is there a PR template? - Are there branch protection rules on main? *CI/CD pipeline:* - Does a CI config exist? (.github/workflows/, etc.) - What checks run automatically? (typecheck, lint, tests, build, security audit) - Does deployment happen automatically on merge to main? - Is there a staging/preview environment? **Scoring guide:** - 0-2: No CI/CD, no branch strategy - 3-4: Basic CI with lint or build check only - 5-6: CI runs lint + typecheck + build, manual deployment - 7-8: CI runs full suite, auto-deploy on merge, preview environments - 9-10: Full pipeline with branch protection, PR template, automated security audit, preview deployments, and rollback capability --- ## Category 9: Performance & Production Readiness (0-10) The gap between "it works" and "it's production-ready." **What to check:** *Error handling:* - Global error boundary (React: error.tsx / ErrorBoundary component) - API error responses are structured and consistent - Errors are logged with context (not swallowed silently) - User-facing error states exist (not blank screens) *Loading states:* - Skeleton loaders or loading indicators on data-fetching pages - Suspense boundaries where appropriate - No blank/flash states during navigation *Performance:* - Images optimized (next/image, srcset, lazy loading) - No N+1 database queries - Proper caching headers on static assets - Bundle size reasonable - Lazy loading for below-fold content *Production configuration:* - Environment-specific config (dev vs. production) - Error monitoring configured (Sentry, LogRocket, etc.) - Analytics configured (even basic) - Favicon, meta tags, Open Graph tags **Scoring guide:** - 0-2: No error boundaries, no loading states, unoptimized images - 3-4: Basic error handling, some loading states, no monitoring - 5-6: Error boundaries exist, loading states on key pages, images optimized - 7-8: Solid error handling + loading states + optimized assets + monitoring - 9-10: Comprehensive — error monitoring, analytics, optimized bundle, proper caching, all production configs --- ## Category 10: Cost Efficiency (0-10) How efficiently the Claude Code setup uses tokens and context window. **What to check:** *CLAUDE.md bloat:* - Count lines in CLAUDE.md. Over 200 = concern. Over 300 = problem. - Does CLAUDE.md load large files unconditionally? - Calculate token impact: each line ≈ 12 tokens - Are reference docs loaded via skills (on-demand) or CLAUDE.md (every session)? *Context management:* - Is domain knowledge in skills (loads when relevant) vs. CLAUDE.md (loads always)? - Are there conditional reading instructions? ("Read X only when working on Y") - Are there duplicate instructions between CLAUDE.md and skills/MEMORY.md? *Workflow efficiency:* - Do specific file references use @file syntax? - Are prompts specific enough to avoid multi-turn clarification? - Is there a model switching strategy? (Sonnet for routine, Opus for complex) **Scoring guide:** - 0-2: CLAUDE.md over 300 lines, loads multiple large files every session, no skills - 3-4: Moderately bloated CLAUDE.md, some redundancy, no skills for offloading - 5-6: Reasonable CLAUDE.md size, some skills exist but knowledge isn't fully migrated - 7-8: Lean CLAUDE.md, skills handle domain knowledge, conditional doc loading - 9-10: Optimized — lean CLAUDE.md, comprehensive skills, conditional loading, model strategy, no redundancy --- ## Generating the Fix Kit After scoring all 10 categories, generate a prioritized fix kit. ### Prioritization Rules 1. **Sort by impact-to-effort ratio** — a 5-minute hook setup that gains +8 points ranks above a half-day refactor that gains +1 point 2. **Group into tiers:** - **Tier 1: Do Today** (under 15 minutes each, zero/low risk) - **Tier 2: Do This Week** (30-60 minutes each, low/medium risk) - **Tier 3: Do This Month** (1+ hours, may need staging/local dev to test) - **Tier 4: Backlog** (nice-to-have, do when convenient) 3. **For each fix, include:** - What to change (specific files) - How to change it (code, commands, or configs — copy-pasteable when possible) - Risk level (None / Low / Medium / High) - Production impact (will this affect live users?) - Dependencies (needs Docker, staging environment, etc.?) ### Stage-Appropriate Advice Consider the project's maturity when prioritizing: | Stage | User Count | Priority | |-------|-----------|----------| | Pre-launch | 0 | Foundation: CLAUDE.md, skills, hooks, basic security | | Early | 1-50 | Ship features, maintain security basics, don't over-optimize | | Growing | 50-500 | Testing coverage, performance, monitoring, CSP headers | | Scale | 500+ | Comprehensive security, E2E testing, performance optimization | **IMPORTANT:** Always note when a fix is "best practice" vs. "critical for current stage." A solo developer with 5 users has different priorities than a team with 500 users. Don't recommend spending a day on test coverage when the developer should be shipping features. --- ## Report Template ```markdown # Project Audit Report **Project:** [name] **Date:** [date] **Overall Score:** [X]/100 ## Score Summary | Category | Score | Status | Notes | |----------|-------|--------|-------| | CLAUDE.md Quality | X/10 | 🟢/🟡/🔴 | [one-line summary] | | Skills & Commands | X/10 | 🟢/🟡/🔴 | | | Hooks Configuration | X/10 | 🟢/🟡/🔴 | | | MCP Servers | X/10 | 🟢/🟡/🔴 | | | Project Structure | X/10 | 🟢/🟡/🔴 | | | Security | X/10 | 🟢/🟡/🔴 | | | Testing | X/10 | 🟢/🟡/🔴 | | | Git & CI/CD | X/10 | 🟢/🟡/🔴 | | | Performance | X/10 | 🟢/🟡/🔴 | | | Cost Efficiency | X/10 | 🟢/🟡/🔴 | | Status: 🟢 8-10 | 🟡 5-7 | 🔴 0-4 ## Detailed Findings [Per-category breakdown with evidence] ## Fix Kit ### Tier 1: Do Today ### Tier 2: Do This Week ### Tier 3: Do This Month ### Tier 4: Backlog ## Top 3 Quick Wins 1. [Specific action] — [time estimate] — [point impact] 2. [Specific action] — [time estimate] — [point impact] 3. [Specific action] — [time estimate] — [point impact] ``` --- ## How to Use This Skill **Run a full audit:** ``` Run the project-audit skill on this project. Read all relevant files and produce the full report. ``` **Audit a specific category:** ``` Run the project-audit skill — Security category only. Detailed findings and fixes. ``` **Re-audit after fixes:** ``` Run the project-audit skill again. Compare against docs/audit-report.md and show what improved. ``` **Audit a new project:** ``` Run the project-audit skill. Fresh project — focus on foundation setup. ``` --- ## Installation 1. Create the directory: `.claude/skills/project-audit/` 2. Save this file as `SKILL.md` inside that directory 3. Restart Claude Code The skill auto-loads whenever you ask Claude to audit, review, or evaluate your project setup.