Agent skill

Project Health Auditor

by majiayu000 in majiayu000/spellbook

Comprehensive codebase health analysis. An agent skill from majiayu000/spellbook.

MITAuto-check: notesDevelopment

Install Project Health Auditor

skills CLI
$ npx skills add majiayu000/spellbook --skill project-health-auditor -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install majiayu000/spellbook project-health-auditor --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/majiayu000/spellbook.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/project-health-auditor .claude/skills/project-health-auditor && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
project-health-auditor
GitHub stars
287
Token cost
~1.7k tokens
SKILL.md length
277 words
Files
1
Skills in repo
97
Repo updated
First seen
Licence
MIT

At a glance

Comprehensive codebase health analysis. An agent skill from majiayu000/spellbook.

  • Works in 6 steps: Code Quality → Dependencies → Security → …
  • Reviewing code quality
  • SKILL.md covers Purpose, Audit Categories, Health Report Template and Quick Commands
  • Calls npm, npx and pytest

What it does

Project Health Auditor is an agent skill from majiayu000/spellbook. Comprehensive codebase health analysis. Use when reviewing code quality, identifying technical debt, checking dependencies, or assessing project structure.

Its SKILL.md is about 1.7k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development, covering Code quality and Technical debt. The repository describes itself as: Cross-runtime skills for Claude Code, Codex, and multi-agent workflows. The licence is MIT.

When your agent uses it

  • Reviewing code quality
  • Identifying technical debt
  • Checking dependencies
  • Assessing project structure

Example prompts

  • “/project-health-auditor”

Requirements

  • Node.js
  • Pre-approved tools (allowed-tools): Read, Grep, Glob, Bash

Workflow steps

6 steps, taken from the step headings in SKILL.md.

  1. Code Quality
  2. Dependencies
  3. Security
  4. Testing
  5. Documentation
  6. Architecture

What it can do on your machine

Read from SKILL.md and the folder at commit ed52af7. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves these tools, so the agent can use them without asking each time:

    • Read
    • Grep
    • Glob
    • Bash

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • npm
    • npx
    • pytest

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • github.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Project Health Auditor loads about 1.7k tokens when it runs. Until then it costs about 45 tokens; SKILL.md has 277 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~45
When it runs · the whole SKILL.md, loaded when a task matches
~1.7k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NoteMentions a .env fileSKILL.md:106
    # Check .env is gitignored
  • NoteMentions a .env fileSKILL.md:107
    cat .gitignore | grep ".env"
  • NoteMentions a .env fileSKILL.md:115
    | .env committed | Secret leak | Add to .gitignore |
  • NoteMentions a .env fileSKILL.md:127
    - [ ] .env files gitignored
  • NotePre-approves every shell command (allowed-tools: Bash)SKILL.md
    allowed-tools: Read, Grep, Glob, Bash

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from majiayu000/spellbook at commit ed52af7, republished under its MIT licence (© majiayu000). 277 words, ~1,704 tokens.

Download SKILL.mdSave it as .claude/skills/project-health-auditor/SKILL.md (or your agent's skills folder).
name
project-health-auditor
description
Comprehensive codebase health analysis. Use when reviewing code quality, identifying technical debt, checking dependencies, or assessing project structure.
allowed-tools
Read, Grep, Glob, Bash

Project Health Auditor

Inspired by claude-code-plugins-plus

Purpose

Analyze codebase health across multiple dimensions: code quality, dependencies, security, testing, documentation, and architecture.

Audit Categories

1. Code Quality
Complexity Analysis
bash
# Count lines per file (identify large files)
find src -name "*.ts" -o -name "*.js" | xargs wc -l | sort -n

# Find long functions (over 50 lines)
# Check for deeply nested code
# Identify duplicate code patterns
Code Smells
SmellIndicatorAction
Long files>500 linesSplit into modules
Long functions>50 linesExtract methods
Deep nesting>4 levelsFlatten logic
Many parameters>5 paramsUse objects
Duplicate codeSimilar blocksExtract shared
Dead codeUnused exportsRemove
Magic numbersHardcoded valuesUse constants
Checklist
markdown
## Code Quality Audit
- [ ] No files over 500 lines
- [ ] No functions over 50 lines
- [ ] No nesting deeper than 4 levels
- [ ] No functions with >5 parameters
- [ ] No obvious code duplication
- [ ] No dead/unused code
- [ ] Consistent naming conventions
- [ ] Proper error handling
2. Dependencies
Dependency Health
bash
# Check outdated packages (npm)
npm outdated

# Check for vulnerabilities
npm audit

# Analyze bundle size
npx webpack-bundle-analyzer

# Check unused dependencies
npx depcheck
Evaluation Criteria
MetricHealthyWarningCritical
Outdated (major)01-3>3
Outdated (minor)<55-10>10
Vulnerabilities0Low/MedHigh/Crit
Unused deps01-3>3
Bundle size<500KB500KB-1MB>1MB
Checklist
markdown
## Dependencies Audit
- [ ] No critical vulnerabilities
- [ ] No high vulnerabilities
- [ ] <3 major version updates pending
- [ ] No unused dependencies
- [ ] Lock file in sync
- [ ] Bundle size reasonable
3. Security
Security Checks
bash
# Check for secrets in code
grep -r "password\|secret\|api_key\|token" --include="*.ts" --include="*.js"

# Check for hardcoded credentials
grep -r "Bearer \|Basic " --include="*.ts"

# Check .env is gitignored
cat .gitignore | grep ".env"
Security Audit Points
CheckConcernSolution
Secrets in codeCredential exposureUse env vars
.env committedSecret leakAdd to .gitignore
SQL stringsSQL injectionUse parameterized queries
User input in HTMLXSSSanitize/escape
Outdated depsKnown vulnsUpdate regularly
No rate limitingDoSAdd rate limits
No input validationInjectionValidate all inputs
Checklist
markdown
## Security Audit
- [ ] No hardcoded secrets
- [ ] .env files gitignored
- [ ] Dependencies scanned for vulns
- [ ] Input validation in place
- [ ] Output encoding for XSS
- [ ] SQL injection prevention
- [ ] Authentication implemented
- [ ] Authorization checks exist
4. Testing
Test Coverage Analysis
bash
# Run tests with coverage (npm/jest)
npm test -- --coverage

# Run tests with coverage (pytest)
pytest --cov=src --cov-report=html
Coverage Standards
MetricGoodAcceptablePoor
Line coverage>80%60-80%<60%
Branch coverage>70%50-70%<50%
Function coverage>80%60-80%<60%
Checklist
markdown
## Testing Audit
- [ ] Unit tests exist
- [ ] Integration tests exist
- [ ] Line coverage >60%
- [ ] Critical paths tested
- [ ] Edge cases covered
- [ ] Tests run in CI
- [ ] Test execution <5 min
- [ ] No flaky tests
5. Documentation
Documentation Inventory
bash
# Check for README
ls README.md

# Check for API docs
ls docs/ || ls documentation/

# Check for inline docs (JSDoc, docstrings)
grep -r "@param\|@returns\|Args:\|Returns:" src/
Documentation Standards
Doc TypePurposeRequired
README.mdProject overviewAlways
CONTRIBUTING.mdContribution guideOpen source
API docsEndpoint referenceAPIs
Code commentsComplex logicAs needed
Architecture docsSystem designLarge projects
CHANGELOG.mdVersion historyLibraries
Checklist
markdown
## Documentation Audit
- [ ] README exists and current
- [ ] Installation instructions
- [ ] Usage examples
- [ ] API documentation
- [ ] Contributing guide
- [ ] License specified
- [ ] Complex code documented
6. Architecture
Architecture Review
AspectCheckConcern
CouplingImport chainsTight coupling
CohesionModule sizeGod modules
LayersDirectory structureLayer violations
DependenciesPackage.jsonCircular deps
ConfigHardcoded valuesEnvironment issues
Common Issues
markdown
## Architecture Smells
- Circular dependencies
- God classes/modules
- Feature envy (cross-module reaching)
- Shotgun surgery (changes touch many files)
- Inappropriate intimacy (modules know too much)
Checklist
markdown
## Architecture Audit
- [ ] Clear module boundaries
- [ ] No circular dependencies
- [ ] Proper layer separation
- [ ] Configuration externalized
- [ ] Environment-specific settings
- [ ] Scalability considered
- [ ] Single responsibility

Health Report Template

markdown
# Project Health Report

**Project:** [Name]
**Date:** [Date]
**Auditor:** Claude

## Summary

| Category | Score | Status |
|----------|-------|--------|
| Code Quality | X/10 | 🟢/🟡/🔴 |
| Dependencies | X/10 | 🟢/🟡/🔴 |
| Security | X/10 | 🟢/🟡/🔴 |
| Testing | X/10 | 🟢/🟡/🔴 |
| Documentation | X/10 | 🟢/🟡/🔴 |
| Architecture | X/10 | 🟢/🟡/🔴 |
| **Overall** | **X/10** | **Status** |

## Critical Issues (Fix Immediately)
1. [Issue description]
2. [Issue description]

## High Priority (Fix Soon)
1. [Issue description]
2. [Issue description]

## Recommendations
1. [Recommendation]
2. [Recommendation]

## Technical Debt
- [Debt item with estimated effort]
- [Debt item with estimated effort]

Quick Commands

bash
# Full audit script
echo "=== Code Stats ===" && cloc src/
echo "=== Dependencies ===" && npm outdated
echo "=== Security ===" && npm audit
echo "=== Test Coverage ===" && npm test -- --coverage
echo "=== TODO/FIXME ===" && grep -r "TODO\|FIXME" src/

© majiayu000, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/project-health-auditor of majiayu000/spellbook.

Open the folder on GitHubat commit ed52af7

Compare with similar skills

Project Health Auditor next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Project Health Auditor compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Project Health Auditor this skillmajiayu000/spellbook287—~1.7kAutomated safety check: NotesMIT
Systematic Code Refactoringluongnv89/claude-howto42k—~3kAutomated safety check: PassMIT
Code Refactoring Workflowluongnv89/claude-howto42k—~3.1kAutomated safety check: PassMIT
Ponytail Debt LedgerDietrichGebert/ponytail160k—~453Automated safety check: PassMIT
FIXME Resolvertailcallhq/forgecode7.6k—~1.1kAutomated safety check: PassApache-2.0
DesloppifyGit-on-my-level/codex-autorunner875—~3.4kAutomated safety check: PassMIT

Similar skills

  • Systematic Code Refactoring

    luongnv89/claude-howto

    Guides refactoring in phases based on Martin Fowler's method: research, test coverage check, planning and small tested steps, with your approval at each phase.

    42k GitHub stars~3k tokensUpdated today
    DevelopmentAuto-check passed
  • Code Refactoring Workflow

    luongnv89/claude-howto

    Guides systematic, test-backed refactoring in the style of Martin Fowler, moving through research, planning and small incremental changes with your approval at each phase.

    42k GitHub stars~3.1k tokensUpdated today
    DevelopmentAuto-check passed
  • Ponytail Debt Ledger

    DietrichGebert/ponytail

    Collects every ponytail: comment in a codebase into one debt ledger, flags shortcuts with no upgrade trigger and reports without changing any files.

    160k GitHub stars~453 tokensUpdated yesterday
    DevelopmentAuto-check passed
  • FIXME Resolver

    tailcallhq/forgecode

    Finds every FIXME comment in a codebase, groups related ones across files into one task, implements the work they describe and removes the comments once it is done.

    7.6k GitHub stars~1.1k tokensUpdated today
    DevelopmentAuto-check passed
  • Desloppify

    Git-on-my-level/codex-autorunner

    Codebase health scanner and technical debt tracker. An agent skill from Git-on-my-level/codex-autorunner.

    875 GitHub stars~3.4k tokensUpdated 2 days ago
    DevelopmentAuto-check passed
  • Tech Debt Analyzer

    ailabs-393/ai-labs-claude-skills

    This skill should be used when analyzing technical debt in a codebase, documenting code quality issues, creating technical debt registers, or assessing code maintainability.

    455 GitHub starsUsed in 1 repo~3.9k tokens
    DevelopmentAuto-check passed

More from majiayu000/spellbook

All 97 skills in this repo
  • Skill Ecosystem Doctor

    majiayu000/spellbook

    Audits and repairs how coding-agent Skills are owned, copied and exposed across runtimes, from canonical sources to quarantine and retirement.

    287 GitHub stars~3k tokensUpdated 2 days ago
    Auto-check passed
  • AGENTS.md Scaffold

    majiayu000/spellbook

    Scans a repository for real evidence and proposes, or on request writes, a small stack of root and scoped AGENTS.md files with validation commands and generated-file boundaries.

    287 GitHub stars~1.5k tokensUpdated 2 days ago
    Auto-check passed
  • Product Demo Builder

    majiayu000/spellbook

    Plans, produces or diagnoses evidence-backed product demo videos: script, capture plan, pacing checks and verified final media built on real product behavior.

    287 GitHub stars~3.3k tokensUpdated 2 days ago
    Auto-check passed
  • Flowguard Task Guard

    majiayu000/spellbook

    Single entry point that routes long or ambiguous agent tasks, checks live state, bounds autonomous loops and leaves a resumable handoff.

    287 GitHub stars~2.1k tokensUpdated 2 days ago
    Auto-check passed
  • npm Supply Chain Check

    majiayu000/spellbook

    Scans a repository, its lockfiles and node_modules for known malicious npm package versions and install-time indicators, using a read-only Python scanner.

    287 GitHub stars~1.5k tokensUpdated 2 days ago
    Auto-check passed
  • Product Manager Toolkit

    majiayu000/spellbook

    Product management helpers: a RICE scoring script, an interview transcript analyzer and PRD templates for prioritizing features, synthesizing research and writing requirements.

    287 GitHub stars~2.2k tokensUpdated 2 days ago
    Auto-check passed

Categories

Questions about Project Health Auditor

What does Project Health Auditor do?

Comprehensive codebase health analysis. An agent skill from majiayu000/spellbook. Project Health Auditor is an agent skill from majiayu000/spellbook. Comprehensive codebase health analysis.

When should I use Project Health Auditor?

Project Health Auditor fits situations like: reviewing code quality; identifying technical debt; checking dependencies; assessing project structure.

How do I install Project Health Auditor in Claude Code?

Run `npx skills add majiayu000/spellbook --skill project-health-auditor -a claude-code`. Or copy the skill folder (skills/project-health-auditor in majiayu000/spellbook) into .claude/skills/project-health-auditor in your project. Claude Code loads it when a task matches its description.

How do I install Project Health Auditor in Codex?

Run `npx skills add majiayu000/spellbook --skill project-health-auditor -a codex`. Or copy the skill folder (skills/project-health-auditor in majiayu000/spellbook) into .agents/skills/project-health-auditor in your project. Codex loads it when a task matches its description.

Can I use Project Health Auditor in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add majiayu000/spellbook --skill project-health-auditor -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/project-health-auditor, .gemini/skills/project-health-auditor, .github/skills/project-health-auditor and .opencode/skills/project-health-auditor in your project.

What does Project Health Auditor need to run?

Going by SKILL.md and its folder, Project Health Auditor needs the command-line tools its instructions call (npm, npx and pytest). Our summary lists: Node.js. Its frontmatter pre-approves these tools: Read, Grep, Glob, Bash.

Does Project Health Auditor access the network?

SKILL.md names 1 domain. As links in the text: github.com. This is read from the text; nothing was executed.

Is Project Health Auditor safe to install?

Our automated static check of SKILL.md found notes only (mentions a .env file; pre-approves every shell command (allowed-tools: bash)), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Project Health Auditor use?

Project Health Auditor is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Project Health Auditor use?

About 1.7k tokens (SKILL.md is roughly 6.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Project Health Auditor?

Skills that share tags, products or a category with Project Health Auditor: Systematic Code Refactoring (luongnv89/claude-howto, 42k stars), Code Refactoring Workflow (luongnv89/claude-howto, 42k stars), Ponytail Debt Ledger (DietrichGebert/ponytail, 160k stars) and FIXME Resolver (tailcallhq/forgecode, 7.6k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Project Health Auditor?

majiayu000 (a GitHub user) maintains it in majiayu000/spellbook, which has 287 GitHub stars. The repository holds 97 skills in this directory. The repository was last updated on October 8, 2026.

Source: majiayu000/spellbook on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.