claude-project-docs

Generate concise CLAUDE.md files and agent documentation following best practices. Use when setting up a new project for Claude Code, auditing existing CLAUDE.md, or creating progressive disclosure documentation structure.

⭐8stars🔀2forks📁View on GitHub🕐Updated Dec 23, 2025⬇️3downloads

When & Why to Use This Skill

This Claude skill optimizes the interaction between AI agents and codebases by generating high-leverage CLAUDE.md files and structured agent documentation. By implementing a 'progressive disclosure' strategy and a strict 60-line rule for core context, it ensures that Claude remains efficient, reduces context window bloat, and maintains high accuracy in instruction following during coding sessions.

Use Cases

  • Project Initialization: Automatically generate a concise CLAUDE.md file when starting a new project to help Claude Code understand the tech stack and essential commands immediately.
  • Context Optimization Audit: Analyze and refactor existing, oversized CLAUDE.md files that exceed 300 lines to improve AI performance and reduce token costs.
  • Modular Documentation: Create a structured 'agent_docs/' directory to separate task-specific information like testing protocols, database schemas, and deployment workflows from core project rules.
  • Codebase Onboarding: Help Claude quickly grasp complex project structures and non-negotiable architectural constraints without overwhelming the session context.
nameclaude-project-docs
descriptionGenerate concise CLAUDE.md files and agent documentation following best practices. Use when setting up a new project for Claude Code, auditing existing CLAUDE.md, or creating progressive disclosure documentation structure.

Claude Project Docs

Create well-crafted, minimal CLAUDE.md files (~60 lines) with progressive disclosure through agent_docs/.

When to Use

Invoke when user:

  • Asks to "set up Claude for this project" or "create a CLAUDE.md"
  • Wants to "audit" or "improve" their existing CLAUDE.md
  • Needs to create agent documentation or progressive disclosure structure
  • Says "help Claude understand this codebase"

Core Methodology

The 60-Line Rule

CLAUDE.md goes into EVERY session. Keep it:

  • < 60 lines ideal (HumanLayer recommendation)
  • < 300 lines absolute maximum
  • Universally applicable - no task-specific content

WHAT/WHY/HOW Structure

# Project Name

[One sentence: what this is]

## Tech Stack
- [Framework/Language]
- [Key dependencies]

## Project Structure
[3-5 line overview of directories that matter]

## Development
[Essential commands only - build, test, run]

## Critical Rules
[2-3 non-negotiable constraints]

## Reference Documentation
When working on specific tasks, read:
- `agent_docs/[topic].md`

Progressive Disclosure

Create agent_docs/ for task-specific documentation:

File Content
building.md Build commands, compilation, bundling
testing.md Test commands, coverage, fixtures
architecture.md System design, key decisions
database.md Schema, migrations, connections
deployment.md Deploy process, environments

Claude reads these ON DEMAND, not every session.

Anti-Patterns to Prevent

NEVER include in CLAUDE.md:

  • Code style rules (use ESLint/Prettier/linters)
  • Full command documentation (use agent_docs/)
  • Implementation examples (point to actual code)
  • 300 lines of content

  • Generic boilerplate from /init

Why: LLMs follow ~150-200 instructions reliably. Every unnecessary line degrades compliance.

Workflow

1. Generate New CLAUDE.md

User: Set up Claude for this project
→ Analyze: package.json, pyproject.toml, go.mod, Makefile
→ Generate: Minimal CLAUDE.md (~60 lines)
→ Create: agent_docs/ structure

2. Audit Existing CLAUDE.md

User: Audit my CLAUDE.md
→ Check: Line count, anti-patterns, task-specific content
→ Report: Issues found with severity
→ Suggest: Specific removals and agent_docs/ migrations

3. Create Agent Docs

User: Create agent docs for testing
→ Generate: agent_docs/testing.md with project-specific content
→ Update: CLAUDE.md reference section

Output Format

When generating CLAUDE.md:

  1. Show the complete file content
  2. Explain what was included and why
  3. List what was intentionally excluded
  4. Suggest agent_docs/ files to create next

References

For templates and examples:

  • references/claude-md-template.md - Minimal starter template
  • references/agent-docs-catalog.md - Complete agent_docs file list
  • references/anti-patterns.md - Detailed anti-pattern guide
  • references/examples/ - Project-type examples

Principle: High leverage documentation. Every line in CLAUDE.md costs context across all sessions.