Important
This repository is archived and no longer maintained.
Claude Code now ships with a built-in claude-config-guide agent that bakes the latest official best practices directly into your configuration, and modern Claude Code writes config files well on its own. Combined with the built-in /doctor diagnostic, the niche this project filled has largely been absorbed upstream — which was the original goal. 🎉
Going forward, use claude-config-guide and /doctor instead. The code here remains available for reference, but will not receive further updates.
A skill that health-checks your Claude Code configuration files.
It goes beyond structural linting — detecting semantic conflicts across CLAUDE.md, rules, commands, skills, hooks, and settings. Also supports plugin projects and marketplace repositories (manifest validation, directory structure, cross-component consistency, and more).
demo_en.mp4
Typical linters check file existence, frontmatter syntax, and naming conventions. config-doctor uses a Claude Code skill to inspect what they can't.
| Linters | claude-config-doctor | |
|---|---|---|
| Frontmatter & JSON syntax | ✅ | ✅ |
| File/directory existence | ✅ | ✅ |
| Semantic consistency (e.g. hooks vs permissions conflicts) | ❌ | ✅ |
| Cross-file contradiction detection (CLAUDE.md ↔ rules ↔ settings) | ❌ | ✅ |
| Insights integration (friction patterns → config recommendations) | ❌ | ✅ |
| Best practices sync (fetches latest official docs at runtime) | ❌ | ✅ |
| Deterministic output | ✅ | ❌ (LLM-based) |
For security reasons, this skill is strictly read-only. It only outputs a report and never modifies any files.
If the findings look reasonable, just type something like "update my config based on these findings" into the prompt and Claude Code will optimize your configuration for you. Easy!
> /config-doctor:check
Running full config-doctor health check. Let me gather the initial context.
...
# Claude Code Configuration Health Check
**Date**: 2026-03-30
**Project**: my-app
**Reviewer**: Claude Code /config-doctor:check
**Review iterations**: 0
**Mode**: Full
## Summary
| Section | Status | Issues |
|--------------------------|--------------|--------|
| 0. Global Config | ✅ PASS | 0 |
| 1. CLAUDE.md | ⚠️ WARN | 2 |
| 2. Rules | ✅ PASS | 0 |
| 3. Commands & Skills | ❌ FAIL | 1 |
| 4. Agents | ⏭️ SKIPPED | 0 |
| 5. Hooks | ⚠️ WARN | 1 |
| 6. Cross-file Consistency| ❌ FAIL | 2 |
| 7. Best Practices | ℹ️ ADVISORY | 3 |
| 8. Insights Integration | ℹ️ ADVISORY | 1 |
## Recommended Actions
1. [❌ FAIL] Section 3: Command `deploy.md` references non-existent agent `deployer.md`
2. [❌ FAIL] Section 6: `rm -rf` is in permissions.allow but blocked by PreToolUse hook
3. [⚠️ WARN] Section 1: CLAUDE.md is 247 lines — consider splitting into rules
4. [⚠️ WARN] Section 5: Orphan script `.claude/hooks/old-lint.sh` not wired in settingsAdd the marketplace and install the plugin.
# add marketplace
/plugin marketplace add tyabu12/claude-config-doctor
# install
/plugin install config-doctor@tyabu12-claude-config-doctor
# reload to activate
/reload-pluginsManual installation (without plugin system)
Copy the skill files from skills/check/ directly into your project:
mkdir -p .claude/skills/config-doctor
for f in SKILL.md plugin.md project.md reference.md; do
curl -fsSL "https://raw.githubusercontent.com/tyabu12/claude-config-doctor/main/skills/check/$f" \
-o ".claude/skills/config-doctor/$f"
doneWhen installed manually, the command is /config-doctor instead of /config-doctor:check.
Tip: Run
/insightsbefore a full check to refresh session data for the most accurate results.
# Recommended monthly: full check (best practices search, `/insights` report analysis)
/config-doctor:check
# Light mode: structural checks only
/config-doctor:check lightThe skill automatically detects the project type (standard project, plugin, or marketplace) and runs the appropriate diagnostics.
| Section | What it checks |
|---|---|
| 0. Global Config | ~/.claude/ globals, .claudeignore relevance |
| 1. CLAUDE.md | Line count, encoding, path accuracy, tech stack drift, staleness |
| 2. Rules | Frontmatter, glob patterns, content accuracy, CLAUDE.md consistency |
| 3. Commands & Skills | Syntax, tool permissions, procedure accuracy, supporting files, agent cross-refs |
| 4. Agents | Required fields, tool lists, model values, evaluation criteria |
| 5. Hooks | Orphan scripts, matcher correctness, script logic, exit codes, frontmatter hooks |
| 6. Cross-file | JSON validity, permission conflicts, hook-permission alignment |
| 7. Best Practices | Fetches latest Anthropic docs at runtime and compares against your config |
| 8. Insights | Aggregates /insights friction data into actionable config fixes |
Plugin projects (`.claude-plugin/plugin.json`)
| Section | What it checks |
|---|---|
| 0. Manifest | JSON syntax, required fields, name format, version, metadata, userConfig, channels, marketplace.json |
| 1. Directory Structure | Anti-patterns, component directories, README, path traversal, stray .claude/ |
| 2. Skills | SKILL.md existence, frontmatter, description, tool permissions, $ARGUMENTS, ${CLAUDE_PLUGIN_ROOT} |
| 3. Commands | Frontmatter, description, tool permissions, legacy overlap with skills |
| 4. Agents | Required fields, supported fields, model, tools, isolation, security restrictions |
| 5. Hooks | hooks.json syntax, event names, handler structure, script portability, orphan scripts |
| 6. MCP & LSP | JSON syntax, server entries, portability, channel references, extension format |
| 7. Cross-Component | Skill↔Agent refs, hook→script refs, channel→MCP refs, namespace conflicts |
| 8. Best Practices | Fetches latest Anthropic plugin docs at runtime and compares against your config |
Marketplace repositories (`.claude-plugin/marketplace.json` without `plugin.json`)
Marketplace repos are automatically detected and each local plugin listed in marketplace.json receives the full plugin diagnostic above. Remote plugin entries are validated for source structure only.
FAIL items are cross-reviewed by a sandboxed subagent (max 1 iteration) before the final report.
Because this skill reads local session data, it is designed with security in mind while maintaining practical utility.
- Strictly read-only — never modifies any files
- Prompt injection defense — all config file content and web content is treated as data to analyze, never as instructions to follow
- Scoped web access — WebSearch and WebFetch are restricted to a hardcoded allowlist of official Anthropic domains only. No project-specific information ever leaves your machine via search queries
- Output sanitization — findings reference file paths and line numbers, never quoting content verbatim, preventing second-order injection if the report is shared
- Subagent sandboxing — cross-review subagents are limited to
Read, Glob, Greponly - Insights privacy — session data is aggregated into abstract recommendations; per-session behavioral details are never included in the report
Yes. config-doctor is LLM-based, so results are non-deterministic. Minor wording differences between runs are expected. If a finding disappears on re-run, it was likely a borderline case. Consider it a soft signal rather than a confirmed issue.
light— structural checks only (Read,Glob,Grep,Bash,Agent). Fast, good for routine use.full(default) — adds best practices search and/insightsanalysis (WebSearch,WebFetch,Agent). Takes about 5 minutes. Recommended monthly or after major config changes.
The skill automatically uses the Opus model in both modes to ensure check accuracy.
No. config-doctor is strictly read-only and never modifies any files. After reviewing the report, type something like update my config based on these findings into the prompt and Claude Code will apply the fixes for you.
Yes. config-doctor runs its own check on itself (dogfooding). The development repository includes a /self-check command that executes /config-doctor:check against its own plugin structure.
Self-check output (Phase 1 only)
❯ /self-check
Claude Code Plugin Health Check
Date: 2026-06-11
Plugin: config-doctor
Reviewer: Claude Code /config-doctor:check
Review iterations: 0
Summary
┌────────────────────────────────┬─────────────┬────────┐
│ Section │ Status │ Issues │
├────────────────────────────────┼─────────────┼────────┤
│ 0. Manifest │ ✅ PASS │ 0 │
├────────────────────────────────┼─────────────┼────────┤
│ 1. Directory Structure │ ⚠️ WARN │ 2 │
├────────────────────────────────┼─────────────┼────────┤
│ 2. Skills │ ✅ PASS │ 0 │
├────────────────────────────────┼─────────────┼────────┤
│ 3. Commands │ ⏭️ SKIPPED │ 0 │
├────────────────────────────────┼─────────────┼────────┤
│ 4. Agents │ ⏭️ SKIPPED │ 0 │
├────────────────────────────────┼─────────────┼────────┤
│ 5. Hooks │ ⏭️ SKIPPED │ 0 │
├────────────────────────────────┼─────────────┼────────┤
│ 6. MCP & LSP │ ⏭️ SKIPPED │ 0 │
├────────────────────────────────┼─────────────┼────────┤
│ 7. Cross-Component Consistency │ ✅ PASS │ 0 │
├────────────────────────────────┼─────────────┼────────┤
│ 8. Best Practices │ ℹ️ ADVISORY │ 1 │
└────────────────────────────────┴─────────────┴────────┘
Section Details
0. Manifest Validation — ✅ PASS
plugin.json:
- JSON syntax: valid
- Required field name: present, non-empty string ("config-doctor")
- Name format: kebab-case — valid
- Version "1.1.3": valid semver
- Description: present, non-empty string
- Author: object with name field — valid
- Optional metadata: repository (valid URL string), license (string), keywords (array of strings) — all valid
- No component path overrides, userConfig, or channels defined
- No settings.json at plugin root
- No unknown top-level fields
marketplace.json:
- JSON syntax: valid
- Required fields: name, owner, plugins — all present
- Name format "tyabu12-claude-config-doctor": kebab-case — valid
- Owner: has name field — valid
- Metadata: description present (string) — valid
- Plugin entry: name "config-doctor" (kebab-case), source "./" (starts with ./, resolves to existing directory) — valid
- Description: present, non-empty string — valid
- Plugin name consistency: marketplace entry "config-doctor" matches plugin.json "config-doctor"; descriptions match
- No unknown top-level fields
1. Directory Structure — ⚠️ WARN (2)
- Anti-pattern check: .claude-plugin/ contains only plugin.json and marketplace.json — no component directories inside. PASS
- Component directories: skills/ exists at root with skill content. No commands/, agents/, hooks/, output-styles/, .mcp.json, or .lsp.json — expected for this plugin's scope
- README.md: exists at plugin root. PASS
- Path traversal: no component files reference paths outside the plugin root. PASS
- ⚠️ WARN: Stray .claude/ directory exists alongside .claude-plugin/. Contains settings.local.json (local dev permissions) and skills/self-check/ (development-only
self-diagnostics). CONTRIBUTING.md (lines 45–50) documents this as intentional. Acknowledged as expected per CLAUDE.md.
- ⚠️ WARN: Procedure/documentation inconsistency. skills/check/plugin.md:90 instructs "If documented, report as PASS," but CONTRIBUTING.md:50 and CLAUDE.md describe the
diagnostic as flagging this WARN. The literal procedure yields PASS while the documented expectation is WARN — recommend reconciling the procedure wording with the docs.
2. Skills Validation — ✅ PASS
Skill: skills/check/ (self-skip rule overridden per /self-check instructions)
- SKILL.md exists: yes
- Frontmatter syntax: well-formed YAML
- description: present, ~236 characters (under 250 limit)
- allowed-tools: Read, Glob, Grep, WebSearch, WebFetch, Bash, Agent — all valid per reference.md
- model: opus — valid
- disable-model-invocation: true — valid boolean
- argument-hint: "[light | full]" — valid string
- Supporting files: plugin.md, project.md, reference.md — all referenced and all exist in the skill directory
- $ARGUMENTS usage: argument-hint is defined and $ARGUMENTS is referenced in SKILL.md and delegated procedure files
- Script references: none (no scripts to check)
3. Commands — ⏭️ SKIPPED
No commands/ directory exists.
4. Agents — ⏭️ SKIPPED
No agents/ directory exists.
5. Hooks — ⏭️ SKIPPED
No hooks/hooks.json, no inline hooks in plugin.json, no hooks/ directory.
6. MCP & LSP — ⏭️ SKIPPED
No .mcp.json, .lsp.json, or inline MCP/LSP config in plugin.json.
7. Cross-Component Consistency — ✅ PASS
- Skill→Agent references: none (no agents referenced)
- Command→Agent references: no commands
- Agent→Skill references: no agents
- Hook→Script references: no hooks
- Channel→MCP references: no channels
- Manifest→Component consistency: no custom component paths in manifest; default skills/ directory contains expected skill files
- Namespace consistency: only skills/ exists, no commands/ — no naming conflicts
- settings.json alignment: no settings.json at plugin root
8. Best Practices (Advisory) — ℹ️ ADVISORY (1)
Compared against official documentation from code.claude.com (plugins, plugins-reference, skills pages).
- Plugin structure: follows standard layout. PASS
- Skill vs command preference: uses skills/ directory (recommended). PASS
- Portability: no scripts or hardcoded paths — not applicable. PASS
- Validation support: claude plugin validate . is documented in CONTRIBUTING.md step 5. PASS
- Hook event names: reference.md hook event list matches the official plugins-reference documentation exactly (26 events including PermissionDenied). PASS
- ℹ️ ADVISORY: Official docs document newer plugin features including output styles (output-styles/), LSP servers (.lsp.json), channels, userConfig, bin/ directory for
executables, and settings.json with agent key for default agent activation. These are not relevant to this plugin's current scope but could be adopted if future development
warrants them.
Sources: https://code.claude.com/docs/en/plugins-reference, https://code.claude.com/docs/en/plugins, https://code.claude.com/docs/en/skills
Recommended Actions
1. [⚠️ WARN — Section 1] Reconcile the stray-.claude/ rating logic: skills/check/plugin.md:90 says "report as PASS" when documented, but CONTRIBUTING.md:50 and CLAUDE.md say
the diagnostic flags it WARN. Either update plugin.md:90 to keep WARN-with-justification, or update the two docs to reflect PASS-when-documented.
2. [⚠️ WARN — Section 1] .claude/ directory exists alongside .claude-plugin/. Documented as intentional in CONTRIBUTING.md — no action needed unless the project structure
changes.
3. [ℹ️ ADVISORY — Section 8] Consider evaluating newer plugin features (output styles, LSP servers, channels, userConfig, bin/) if future development warrants them./plugin uninstall config-doctor@tyabu12-claude-config-doctorIf installed manually, delete .claude/skills/config-doctor/.
Claude Code's built-in /doctor command diagnoses and verifies your installation and settings. config-doctor focuses on semantic configuration analysis (cross-file conflicts, best practices, insights integration) that /doctor does not cover. Run /doctor first to ensure your environment is healthy, then config-doctor to optimize your configuration.
Anthropic's official claude-md-management plugin audits and improves CLAUDE.md files. config-doctor diagnoses your entire configuration (read-only); claude-md-management edits CLAUDE.md after approval. The two are complementary.
rulesync generates configuration for many AI coding assistants (Claude Code, Cursor, Copilot, Gemini CLI, etc.) from a single shared source. config-doctor can validate the generated Claude Code output, catching spec drift or semantic issues that the generation step might miss. Use rulesync to generate, then config-doctor to verify.
See CONTRIBUTING.md for guidelines.