[Feature Request] Built-in project configuration validation that pulls rules from live documentation

Problem

Claude Code has specific project scaffolding conventions (skills, MCP, hooks, settings, CLAUDE.md), but there's no built-in way to validate that a project is configured correctly. Users discover issues through runtime failures—or worse, never discover them at all and assume Claude is less capable than it actually is.

The existing /doctor command focuses on installation health, not project configuration health.

My Personal Experience

I've been a heavy Claude Code user for the past couple of months, and this gap has bitten me hard:

Skills in wrong location for 3+ weeks: I had my skill files under module-specific subfolders (e.g., email/skill/SKILL.md, calendar/skill/SKILL.md) instead of the correct location (.claude/skills/email/SKILL.md). Many things still worked—the CLI paths were valid, the documentation files were readable—so I didn't realize my skills weren't being discovered.

The real cost: I genuinely thought Claude was less capable than it actually is. I was missing out on skill-based workflows entirely. I only found out after manually auditing my setup against the documentation weeks later.

MCP still broken after 6 weeks: Even now, a month and a half in, I discovered through a manual audit that my .mcp.json was missing a server that my CLAUDE.md claimed was configured.

The Core Problem with Community Solutions

I've looked at audit skills in the marketplace, and I've built my own. They all share the same fundamental problem:

Hardcoded rules become stale. Any skill that says "skills must be in .claude/skills/" or "CLAUDE.md should be under 500 lines" is encoding a point-in-time understanding of Claude Code's conventions. As the product evolves, these rules drift.

No single source of truth. Community skills encode what the author thinks is correct, which may not match Anthropic's actual conventions. Users can't trust that a third-party skill reflects official best practices.

Proposed Solution: Dynamic Validation from Live Documentation

The key insight is that Anthropic already maintains the source of truth: the official documentation at code.claude.com/docs/. A built-in validation feature should pull validation rules from the documentation dynamically, not hardcode them.

Architecture

I built a custom /audit skill that demonstrates this approach:

## Phase 1: Fetch Latest Documentation

Fetch these documentation pages to get current best practices:

1. Skills: https://code.claude.com/docs/en/skills
2. MCP: https://code.claude.com/docs/en/mcp
3. Memory/CLAUDE.md: https://code.claude.com/docs/en/memory
4. Settings: https://code.claude.com/docs/en/settings
5. Hooks: https://code.claude.com/docs/en/hooks

## Phase 2: Validate Configuration

[Apply what was learned from the documentation to the current project]

The validation rules aren't hardcoded—they're derived from the documentation at runtime. This means:

• Future-proof: As conventions change, validation stays current
• Authoritative: Rules come from Anthropic's official docs
• Self-documenting: Each finding can link to the relevant documentation

What Could Be Validated (Examples, Not Prescriptions)

These are examples of the types of things that could be checked—the actual rules should be derived from documentation:

• Skills: Are they in the expected location? Do they have required frontmatter fields? Do referenced files exist?
• MCP: Is the JSON valid? Do server commands exist? Are transport types recognized?
• CLAUDE.md: Does it exist? Are imports resolvable? Is it within recommended length?
• Hooks: Do scripts have valid syntax? Are event types recognized?
• Settings: Is JSON valid? Are permission patterns well-formed?

The specific rules for each category would be extracted from the documentation, not hardcoded into the feature.

Example Output

$ claude doctor --project

Fetching latest conventions from documentation...
✓ Loaded rules from code.claude.com/docs/en/skills
✓ Loaded rules from code.claude.com/docs/en/mcp
✓ Loaded rules from code.claude.com/docs/en/memory
...

Validating project configuration...

✓ CLAUDE.md exists (302 lines)
✓ .mcp.json is valid JSON

⚠ Warning: CLAUDE.md approaching recommended length limit
  Reference: https://code.claude.com/docs/en/memory#determine-memory-type

✗ Error: Found skill at email/skill/SKILL.md
  Skills should be in .claude/skills/ directory
  Reference: https://code.claude.com/docs/en/skills#where-skills-live

Found 1 error, 1 warning

Why This Should Be Built-In

1. Anthropic controls the source of truth. You maintain the documentation. A built-in tool can leverage that authoritative source in ways community solutions cannot.

1. Dynamic updates. When conventions change, the documentation changes, and validation automatically reflects the new rules.

1. Trust. Users can trust that validation reflects official best practices, not one developer's interpretation.

1. Reduced friction. Silent misconfigurations erode trust in the product. Catching them early improves the user experience significantly.

Reference Implementation

I've built a custom /audit skill that demonstrates the documentation-first approach. Happy to share the full implementation if helpful. The key design principle is:

Phase 1 fetches from live documentation. Phase 2 applies what was learned. No hardcoded rules outside of pointers to docs.

This ensures the skill stays current as Claude Code evolves, and could serve as a pattern for a built-in feature.