Doctor

46 automated checks across 6 layers. Adaptive scoring. Field-tested on real projects.

A Claude Code skill that audits any project — security gaps, broken hooks, missing tests, misconfigured CI. Auto-detects your stack (20+ languages), adapts scoring to maturity level, and provides concrete fixes with source links.

What It Does · Adaptive Scoring · 6 Layers · Install · Usage · How It Works · Example Output · FAQ

Install in 5 seconds:

curl -sSL https://raw.githubusercontent.com/SomeStay07/claude-doctor-skill/main/install.sh | bash

---

The Problem

You set up Claude Code and start building. Everything seems fine — until you realize:

• Secrets are committed to git history
• .env files are world-readable (permissions 644)
• No pre-commit hooks catch broken code
• No CI runs tests automatically
• Claude has no memory of past decisions
• No domain rules — Claude repeats the same mistakes

You don't know what you don't know. Doctor finds out for you.

What It Does

Doctor is a set of .md files that turns Claude Code into a project auditor. Run /doctor and get a full health report with severity levels, explanations, and one-click fixes.

What's a Claude Code skill? A .md file in .claude/skills/ that gives Claude specialized behavior. No plugins, no API keys — just text files. Learn more

Every finding is project-specific (not a template) and explains WHY it matters, with a source link.

/doctor scan — Diagnose

/doctor fix — Prescribe + Apply

At a Glance

| | | |:--|:--| | 46 checks across 6 security & automation layers | 20+ stacks auto-detected at startup | | Adaptive scoring — 4 maturity levels | 14 false positive rules — no noise | | Self-validates before output (10-point check) | Incident response — 9-step recovery for leaked secrets | | Zero dependencies — just .md files | Bilingual — English and Russian | | Field-tested — 89 bugs found and fixed across 4 rounds on real projects | Graceful degradation — handles missing git, no tests, context overflow |

Adaptive Scoring

Doctor auto-detects your project's maturity and adapts — which checks count, layer weights, score thresholds, even terminology. Everyone gets a fair score.

| Level | Detected when | Checks | Description | |:------|:-------------|:------:|:------------| | Starter | No git, or no tests/CI/linter | 18 | Core checks only — security + foundations | | Growing | Git + deps + (tests or linter) | 27 | Adds quality gate checks | | Mature | Tests + linter + (CI or env) | 34 | Adds advanced practices | | Pro | Mature + Claude Code automation | 46 | All checks including CC-specific |

Weighted Layer Scoring

| Layer | Starter | Growing | Mature | Pro | |:------|:-------:|:-------:|:------:|:---:| | Security | 50% | 30% | 25% | 20% | | Foundation | 35% | 25% | 20% | 15% | | Quality | 15% | 30% | 25% | 20% | | Intelligence | — | 5% | 10% | 15% | | Context | — | 5% | 10% | 15% | | DX | — | 5% | 10% | 15% |

— = layer shown as bonus, weight 0%. Checks beyond your level appear as Bonus (visible but don't affect score).

/doctor quick — 30-Second Audit

QUICK AUDIT (Growing)
========================
Core score: 15/19 (79%)

TOP-3 PRIORITIES:
1. chmod 600 .env — secrets are world-readable
2. Add pre-commit hook — broken code reaches git
3. Add .env.example — new devs can't onboard

> /doctor for full audit (46 checks)

6 Layers, 46 Checks

Layers are ordered by priority — you can't work on DX if Security is broken:

| Layer | Name | Checks | What It Covers | |:------|:-----|:------:|:---------------| | 0 | Security | 13 | Secrets in git, SAST, .gitignore, .env permissions, Docker security, client-side keys, AI API cost protection, backup strategy, incident response | | 1 | Foundation | 7 | CLAUDE.md, README.md, dependency manifest, build scripts, project structure, dep freshness, DB migrations | | 2 | Quality Gates | 12 | Linter, PostToolUse/PreToolUse hooks, pre-commit, CI, error handling, types, coverage, error monitoring | | 3 | Intelligence | 2 | Agent trio (code-reviewer, debugger, architect), domain rules with paths: | | 4 | Context | 5 | MCP servers, plugins (context7, episodic-memory), memory files, SessionStart hook | | 5 | DX | 7 | Skills (/test, /status), hook installer, Dependabot, stop hook, unit & smoke tests |

Severity Levels

| Level | Meaning | Example | |:------|:--------|:--------| | :red_circle: Critical | Breach risk, data loss | Secrets in git history, .env world-readable | | :orange_circle: Important | Code quality, team burden | No pre-commit hooks, no CI | | :yellow_circle: Medium | Nice-to-have improvement | Missing Dependabot, no smoke tests | | :large_blue_circle: Minor | Cosmetic or context-dependent | Missing stop hook, no SessionStart |

Example Output

Project Profile (Phase 1)

Project Profile
  Stack:        Python 3.12 / asyncio / PostgreSQL
  Entry Point:  src/main.py
  Test Runner:  pytest, 1089 tests
  Linter:       ruff check + ruff format
  CI/CD:        GitHub Actions
  Deploy:       Railway (Docker)

Finding Format (Phase 3)

[Critical] chmod 600 .env .mcp.json
   Secrets are world-readable (644). Any process on the machine can read them.
   > https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html

[Important] Added *.pem *.key *.p12 to .gitignore
   git add . will push private keys to remote. Once in history, removing is painful.
   > https://docs.github.com/en/authentication/keeping-your-account-and-data-secure

No vague "consider improving security." Every fix has a concrete command, a reason, and a source.

Installation

Doctor is just .md files — no binaries, no plugins, no API keys.

Option A: One command (recommended)

curl -sSL https://raw.githubusercontent.com/SomeStay07/claude-doctor-skill/main/install.sh | bash

Downloads 15 .md files into .claude/skills/doctor/ and verifies each one.

Want to inspect first? View install.sh — it only creates a directory and downloads .md files.

Option B: Manual

mkdir -p .claude/skills/doctor/layers
cd .claude/skills/doctor

# Main files
curl -sO https://raw.githubusercontent.com/SomeStay07/claude-doctor-skill/main/SKILL.md
curl -sO https://raw.githubusercontent.com/SomeStay07/claude-doctor-skill/main/GUARDRAILS.md
curl -sO https://raw.githubusercontent.com/SomeStay07/claude-doctor-skill/main/CHECKLIST.md

# Layer details
cd layers
for f in SECURITY SECURITY-EXTRA FOUNDATION FOUNDATION-EXTRA QUALITY QUALITY-EXTRA QUALITY-PROD INTELLIGENCE CONTEXT DX DX-EXTRA MATURITY; do
  curl -sO "https://raw.githubusercontent.com/SomeStay07/claude-doctor-skill/main/layers/$f.md"
done

Verify

ls .claude/skills/doctor/SKILL.md && echo "Doctor installed"

Update

Run the install command again — it safely overwrites existing files.

Uninstall

rm -rf .claude/skills/doctor/

Requirements

| Requirement | Details | |:------------|:--------| | Claude Code | Any version with skill support | | OS | macOS, Linux, WSL | | Git | Recommended — some checks skip without it | | Internet | Only needed for installation |

Usage

# In Claude Code:
/doctor              # Full audit — all 6 layers, adaptive scoring
/doctor quick        # TOP-3 priorities + score (30 seconds)
/doctor scan         # Diagnose only (phases 1-2, no file changes)
/doctor fix          # Prescribe + apply fixes (phases 3-4)
/doctor layer 0      # Security audit only
/doctor verify       # Health check after fixes

# Or in natural language:
"audit my project"
"check security"
"what's missing in my setup?"

How It Works

Phase 1:   STUDY        Read project: deps, structure, .env, git, automation
                        Output: Project Profile table

Phase 1.5: MATURITY     Auto-detect maturity level (Starter/Growing/Mature/Pro)
                        Set check profile, layer weights, score thresholds

Phase 2:   DIAGNOSE     Run applicable checks from CHECKLIST.md
                        Score each layer: X/Y (N%) — Y = applicable checks only

Phase 3:   PRESCRIBE    For each finding:
                        severity + what to fix + WHY + source link

Phase 4:   TREAT        Ask user: "Fix all at once or one by one?"
                        Apply project-specific fixes (not templates)

Phase 5:   VERIFY       Run tests, linter, check hooks
                        Output: HEALTH REPORT with total score

Auto-Discovery (DCI)

Doctor automatically detects your stack at startup via Dynamic Context Injection:

package.json / requirements.txt / Cargo.toml    > stack detection
Makefile / justfile / taskfile.yml               > build system
.claude/ / .mcp.json                             > Claude Code setup
Dockerfile / docker-compose.yml                  > containerization
.github/workflows/ / .gitlab-ci.yml              > CI/CD

Works with 20+ stacks out of the box. No configuration needed.

Built-in Guardrails

Self-Check (10 points)

Before showing results, Doctor validates:

1. Every finding has a WHY?
2. Severity matches reality?
3. No duplicate findings?
4. Fixes are project-specific?
5. Score uses only applicable checks?
6. N/A checks excluded from score?
7. Sources exist for all claims?
8. Bonus checks marked correctly?
9. Weighted score uses maturity weights?
10. TOP-3 priorities present?

False Positive Filtering (14 rules)

Doctor won't flag:

• Missing CI in hobby projects
• print() in CLI scripts
• No Docker for Vercel/serverless
• .env 644 on personal Mac
• Missing MCP if Claude Code not used
• Missing Dependabot if using Nix/Guix
• Missing pre-push if CI runs tests

Error Recovery

| Scenario | What Doctor Does | |:---------|:-----------------| | No git repo | Skips git checks, continues with rest | | No tests | Flags it, doesn't crash | | No Docker | Skips Docker checks | | Context overflow | Suggests /doctor layer <N> one at a time | | Check command fails | Logs error, continues with next check | | Missing tool (ruff, eslint) | Recommends install, doesn't block |

Incident Response

If Doctor finds secrets in git history, it provides a 9-step recovery plan: rotate credentials, purge history with git filter-repo, force-push, invalidate sessions, check audit logs, set up gitleaks, add CI scanning, enable GitHub secret scanning, document the incident.

Multi-Stack Support

| Stack | Linter | Formatter | Test Runner | SAST | |:------|:-------|:----------|:------------|:-----| | Python | ruff | ruff format | pytest | bandit | | Node.js | eslint | prettier | jest/vitest | eslint-plugin-security | | TypeScript | eslint + tsc | prettier | jest/vitest | eslint-plugin-security | | Rust | clippy | rustfmt | cargo test | cargo-audit | | Go | golangci-lint | gofmt | go test | gosec | | Ruby | rubocop | rubocop | rspec | brakeman | | Java | checkstyle | google-java-format | JUnit | SpotBugs | | PHP | phpstan | php-cs-fixer | PHPUnit | psalm |

Also detects: C/C++, C#, Swift, Kotlin, Scala, Haskell, Elixir, Dart/Flutter, Zig, and more.

Repository Structure

claude-doctor-skill/
+-- SKILL.md             -- Brain: protocol, subcommands (< 250 lines)
+-- GUARDRAILS.md        -- Output format, error recovery, self-check
+-- CHECKLIST.md         -- Index of all 46 checks across 6 layers
+-- layers/
|   +-- SECURITY.md        -- Layer 0: core security (0a-0i)
|   +-- SECURITY-EXTRA.md  -- Layer 0: advanced security (0j-0m + incident)
|   +-- FOUNDATION.md      -- Layer 1: 6 core foundation checks
|   +-- FOUNDATION-EXTRA.md -- Layer 1: advanced foundation (1g DB migrations)
|   +-- QUALITY.md         -- Layer 2: 6 core quality checks
|   +-- QUALITY-EXTRA.md   -- Layer 2: 5 advanced quality checks
|   +-- QUALITY-PROD.md    -- Layer 2: production quality (2l error monitoring)
|   +-- INTELLIGENCE.md    -- Layer 3: 2 agent intelligence checks
|   +-- CONTEXT.md         -- Layer 4: 5 context & memory checks
|   +-- DX.md              -- Layer 5: core DX (5a-5d)
|   +-- DX-EXTRA.md        -- Layer 5: advanced DX (5e-5g)
|   +-- MATURITY.md        -- Adaptive scoring: maturity detection + weights
+-- assets/
|   +-- logo.svg         -- Doctor logo
|   +-- demo-scan.gif    -- Animated demo: /doctor scan
|   +-- demo-fix.gif     -- Animated demo: /doctor fix
+-- install.sh         -- One-line installer with verification
+-- LICENSE

FAQ

/doctor scan is read-only. /doctor fix proposes changes and asks before touching anything. You approve every change.

No. Doctor is .md files that run locally inside Claude Code. No external API calls, no telemetry. Your code never leaves your machine.

No. Doctor detects existing hooks and won't overwrite them.

Yes. Doctor scans common monorepo patterns (apps/, packages/, services/), detects Turborepo/NestJS/pnpm workspaces, and finds configs up to 3 levels deep.

Doctor is designed for Claude Code CLI. Other editors that support .claude/skills/ may work but are not tested.

Full audit: 8-15 minutes depending on project size. /doctor quick: ~30 seconds for TOP-3 priorities.

Yes — edit the layer .md files in .claude/skills/doctor/layers/. Each check is a markdown section with a description and verification command.

Roadmap

• [ ] Custom check authoring (user-defined checks via .claude/doctor-checks/)
• [ ] GitHub Action integration (run Doctor in CI, fail on Critical findings)
• [ ] Supply chain security checks (SBOM, dependency provenance)
• [ ] Auto-update mechanism (check for newer version on install)

Open an issue or submit a PR.

See Also

Claude Memory Skill — persistent project memory for Claude Code. Remembers decisions, catches contradictions. Pairs well with Doctor: memory stores conventions, Doctor enforces them.

Code Reviewer Agent — automated code review with concrete fixes. Doctor audits the project setup; Code Reviewer audits the code itself.

Author

Made by @SomeStay07 · Telegram Channel

License

MIT — use it, modify it, ship it.