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 | bashYou set up Claude Code and start building. Everything seems fine — until you realize:
- Secrets are committed to git history
.envfiles are world-readable (permissions644)- 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.
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
.mdfile 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.
Phase 1-2: Study your project, run 46 checks, score each layer
Phase 3-4: Severity-tagged findings with one-click fixes, then verification
| 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 |
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 |
| 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).
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)
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 |
| Level | Meaning | Example |
|---|---|---|
| 🔴 Critical | Breach risk, data loss | Secrets in git history, .env world-readable |
| 🟠 Important | Code quality, team burden | No pre-commit hooks, no CI |
| 🟡 Medium | Nice-to-have improvement | Missing Dependabot, no smoke tests |
| 🔵 Minor | Cosmetic or context-dependent | Missing stop hook, no SessionStart |
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)
[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.
Doctor is just .md files — no binaries, no plugins, no API keys.
curl -sSL https://raw.githubusercontent.com/SomeStay07/claude-doctor-skill/main/install.sh | bashDownloads 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
.mdfiles.
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"
donels .claude/skills/doctor/SKILL.md && echo "Doctor installed"Run the install command again — it safely overwrites existing files.
rm -rf .claude/skills/doctor/| 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 |
# 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?"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
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.
|
Before showing results, Doctor validates:
|
Doctor won't flag:
|
| 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 |
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.
| 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.
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
Does Doctor modify my code?
/doctor scan is read-only. /doctor fix proposes changes and asks before touching anything. You approve every change.
Does it send my code anywhere?
No. Doctor is .md files that run locally inside Claude Code. No external API calls, no telemetry. Your code never leaves your machine.
Will it conflict with my pre-commit hooks?
No. Doctor detects existing hooks and won't overwrite them.
Does it work with monorepos?
Yes. Doctor scans common monorepo patterns (apps/, packages/, services/), detects Turborepo/NestJS/pnpm workspaces, and finds configs up to 3 levels deep.
Does it work with Cursor / Windsurf?
Doctor is designed for Claude Code CLI. Other editors that support .claude/skills/ may work but are not tested.
How long does an audit take?
Full audit: 8-15 minutes depending on project size. /doctor quick: ~30 seconds for TOP-3 priorities.
Can I add my own checks?
Yes — edit the layer .md files in .claude/skills/doctor/layers/. Each check is a markdown section with a description and verification command.
- 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.
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.
Made by @SomeStay07 · Telegram Channel
MIT — use it, modify it, ship it.