Claude Config Validation

Claude Config Validation

Validates a project's Claude Code configuration against the knowledge architecture defined in ../../references/knowledge-architecture.md.

Input

• project_path: Path to the project directory (e.g., apps/example-app). Defaults to cwd.

Check Definitions

Read ../../references/config-validation-checks.md for the full reference table — what each check validates, and PASS/WARN/FAIL criteria. The checks are organized in six categories: Project Structure, Knowledge Placement, Skill Quality, Discoverability & References, Compliance Placement, Loading & Registration.

Configuration

Two aspects of this skill are meant to be tuned per repository. Defaults are given; a repo may override them (e.g. in its own copy of this skill or in a CLAUDE.md note):

• Monorepo-root markers — the file/dir markers that identify the monorepo root (see Step 0). Default set: .git, pnpm-workspace.yaml, a package.json containing a workspaces field, lerna.json, nx.json. Adjust to match the repo's tooling.
• Canonical agent roles — the role names treated as root-owned (see Check 2). Default set: architect, coder, test-writer, tester, reviewer, pr-submission, learner. This is a recommended default, not a hard requirement — a repo may define its own role list (fewer, more, or differently named). Validate against whatever set the repo declares; fall back to the default when none is declared.

Steps

0. Resolve Project Path

If no project_path argument was provided and cwd is the monorepo root, do NOT auto-validate root. Detect the monorepo root using the configurable marker set (default: a .git directory, pnpm-workspace.yaml, a package.json whose top-level object has a workspaces field, lerna.json, or nx.json). When at root, list available projects that have .claude/ directories (e.g., apps/example-app, apps/api) and ask the user which project to validate. Root-level .claude/ is the canonical home for the root-owned agents and shared config — validate it only when explicitly requested via project_path.

1. Locate Configuration

Find all Claude Code config files in the project:

• {project_path}/CLAUDE.md
• {project_path}/.claude/agents/*.md
• {project_path}/.claude/skills/*/SKILL.md
• {project_path}/.claude/commands/*.md
• {project_path}/.claude/rules/*.md

If no .claude/ directory exists, report that the project has no Claude Code configuration and stop.

2. Run Project Structure Checks (1–3)

Read checks 1–3 from the check definitions doc. For each:

• Check 1: Verify .claude/ exists
• Check 2 (Canonical agents): List agents in .claude/agents/, then apply the check's PASS/WARN/FAIL columns as written in the reference. Whether you are validating the repo root or a config home determines which column applies; the canonical role set is config-driven (see Configuration).
• Check 3: Parse YAML frontmatter of each agent file. Validate required fields and permission/tool consistency.

3. Run Knowledge Placement Checks (4–7)

Read checks 4–7 from the check definitions doc. For each:

• Check 4: Scan agent body content for file-type conventions that belong in rules. Also check project-level rules for monorepo-wide conventions that belong in root .claude/rules/ instead.
• Check 5: Compare CLAUDE.md content against agent body content for duplication.
• Check 6: Count lines in CLAUDE.md.
• Check 7: Parse rules frontmatter. Distinguish root-level rules (FAIL without paths) from project-level rules (WARN without paths).

4. Run Skill Quality Checks (10–14, 22)

Read checks 10–14 and 22 from the check definitions doc. For each skill in .claude/skills/*/SKILL.md:

• Check 10: Scan for fenced code blocks with language identifiers, external dependencies, large inline data.
• Check 11: Parse skill frontmatter. Check description exists and allowed-tools matches actual tool references in the body.
• Check 12: Verify directory structure follows {skill-name}/SKILL.md convention. Flag flat files and unexpected files.
• Check 13: Compare content across all .claude/ files for blocks of 5+ consecutive near-identical lines.
• Check 14: Count lines per skill. For skills over threshold, scan for domain knowledge that should be extracted (checklists, API docs, templates, config instructions). Apply the location test.
• Check 22 (opt-in): Only run this check when the repo has opted into eval coverage for its skills — it is NOT a universal mandate. When opted in, verify each skill directory contains an eval/ subdirectory with eval.yaml: FAIL if eval/ is missing; WARN if eval/ exists but eval.yaml is missing. When the repo has not opted in, report this check as N/A.

5. Run Discoverability & Reference Checks (8–9, 15–18, 23)

Read checks 8–9, 15–18, and 23 from the check definitions doc. For each:

• Check 8: Scan agents for skill references, verify referenced skills exist.
• Check 9: If CLAUDE.md has a routing table, verify all file paths resolve.
• Check 15: For each domain doc referenced by an agent or skill, verify it appears in the nearest CLAUDE.md routing table, applying the reference's exemptions.
• Check 23: Inspect the CLAUDE.md routing table for context discipline per the reference. Where a doc is duplicated between a path-scoped rule and the routing table, recommend keeping the rule.
• Check 16: Scan skills and commands for references to other skills/commands. Verify targets exist. Flag /-prefixed references where only a skill (not a command) exists. Exclude built-in Claude Code commands (/plan, /init, etc.) — these are runtime features, not project-defined.
• Check 17: If CLAUDE.md has a routing table, verify no entries point to other CLAUDE.md files. Entries may target any concrete destination — a domain doc, a package doc (README.md, docs/DESIGN.md), or a skill. The only FAIL is an entry pointing to another CLAUDE.md (a map pointing to a map).
• Check 18: For each task-recipe domain doc reachable from the routing table, apply the reference's self-containment criteria. Note its scope limit: task recipes only, not package architecture docs.

6. Run Compliance Placement Check (19)

Read check 19 from the check definitions doc. For each skill:

1. Count declarative constraint statements — lines containing "must", "always", "never", "do not", "required" that impose conventions rather than describe procedure steps.
2. Count procedural steps — numbered actions, imperative instructions that produce an output or transform state.
3. Compute the ratio. If constraints outnumber procedural steps 2:1 or more, the skill is primarily a compliance document.
4. WARN if the skill would be more effective as a rule (rules shape plans from the start; skills only execute when invoked).

7. Run Loading & Registration Checks (20–21)

Read checks 20–21 from the check definitions doc.

1. Check 20: Glob for .claude/ directories below the project root (e.g., {project_path}/*/.claude/, {project_path}/**/.claude/). For each nested .claude/ found, check its contents:
   • Contains rules/, skills/, agents/, or settings.json → FAIL (dead config, never loaded)
   • Contains only CLAUDE.md → WARN (should be a plain subdirectory CLAUDE.md, not inside a nested .claude/)
2. Check 21: Scan all CLAUDE.md files (root and subdirectory) for @ import references. If any @ path resolves to a file inside a .claude/ directory, FAIL — the import gives text only, no harness registration.

8. Format Output

## Claude Config Validation: {project_path}

| # | Check | Status | Details |
|---|-------|--------|---------|
| 1 | Config exists | PASS/FAIL | |
| 2 | Canonical agents | PASS/WARN/FAIL | [misplaced/missing agents] |
| 3 | Agent frontmatter | PASS/FAIL | [issues] |
| 4 | Convention placement | PASS/WARN | [conventions in agent prompts] |
| 5 | Duplication | PASS/WARN | [duplicated content] |
| 6 | CLAUDE.md size | PASS/WARN/FAIL | [N lines] |
| 7 | Rules frontmatter | PASS/WARN/FAIL | [issues] |
| 8 | Skill references | PASS/FAIL | [missing skills] |
| 9 | Routing table | PASS/FAIL/N/A | [broken references] |
| 10 | Skill content quality | PASS/FAIL/WARN | [code blocks, external deps, inline data] |
| 11 | Skill frontmatter | PASS/WARN | [missing frontmatter, tool mismatches] |
| 12 | Skill directory structure | PASS/FAIL/WARN | [flat files, unexpected files] |
| 13 | Cross-skill duplication | PASS/WARN | [duplicated content across files] |
| 14 | Skill size & separation | PASS/WARN/FAIL | [N lines, mixed concerns] |
| 15 | Routing table completeness | PASS/WARN | [skills/commands not in routing table] |
| 16 | Cross-file references | PASS/FAIL/WARN | [broken refs, /-prefix mismatches] |
| 17 | Routing table targets | PASS/FAIL | [entries pointing to CLAUDE.md] |
| 18 | Domain doc self-containment | PASS/WARN | [essential steps behind secondary refs] |
| 19 | Compliance placement | PASS/WARN | [skills that should be rules] |
| 20 | Nested `.claude/` directories | PASS/WARN/FAIL | [nested dirs with dead config] |
| 21 | CLAUDE.md `@import` targets | PASS/FAIL | [@imports targeting .claude/ paths] |
| 22 | Skill eval present | PASS/WARN/FAIL/N/A | [opt-in; missing eval/ or eval.yaml] |
| 23 | CLAUDE.md context discipline | PASS/WARN | [multi-doc rows; rule docs duplicated in routing table] |

## Issues

### FAIL
- [file:detail]

### WARN
- [file:detail]

## Recommendations
- [actionable suggestion]

Example commands

Validate the current repository, or a specific project path:

$ /claude-config-validation
$ /claude-config-validation apps/my-project