From lean-docs
Agent-legible documentation setup and auditing for any codebase. Use when the user asks to set up docs, audit docs, create CLAUDE.md, organize documentation, or mentions 'lean docs'. Also use when documentation is clearly missing or disorganized in a project the user is working on.
npx claudepluginhub numanumanuma/claude-plugins --plugin lean-docsThis skill uses the workspace's default tool permissions.
A step-by-step guide to making any codebase agent-legible. Agents work better with a short stable entry point (~100 lines) that links to deeper docs on demand. Think table of contents, not encyclopedia.
Creates new Angular apps using Angular CLI with flags for routing, SSR, SCSS, prefixes, and AI config. Follows best practices for modern TypeScript/Angular development. Use when starting Angular projects.
Generates Angular code and provides architectural guidance for projects, components, services, reactivity with signals, forms, dependency injection, routing, SSR, ARIA accessibility, animations, Tailwind styling, testing, and CLI tooling.
Executes ctx7 CLI to fetch up-to-date library documentation, manage AI coding skills (install/search/generate/remove/suggest), and configure Context7 MCP. Useful for current API refs, skill handling, or agent setup.
A step-by-step guide to making any codebase agent-legible. Agents work better with a short stable entry point (~100 lines) that links to deeper docs on demand. Think table of contents, not encyclopedia.
Your CLAUDE.md should only contain what every task needs:
Everything else moves to docs/. Target: 80-120 lines.
See references/claude-md-template.md for the full template.
docs/)Split your old CLAUDE.md content into topic files. Common set:
| File | What goes in it |
|---|---|
architecture.md | App structure, patterns, directory layout, service lifecycle |
database.md | Tables, key functions/triggers, data model, migration patterns |
api.md | Endpoints, auth, error handling (or realtime.md for WebSocket apps) |
feature-x.md | Per-feature deep docs (only for complex features) |
notifications.md | Push/email notification flow |
ui-patterns.md | Component catalog, layout patterns, design system |
testing.md | Test commands, decoder rules, fixture patterns |
gotchas.md | Hard-won lessons and pitfalls |
quality-grades.md | Per-domain quality table (see template in references) |
Rule of thumb: If a section in CLAUDE.md is >15 lines and only relevant to some tasks, it belongs in a doc file.
Create a CLAUDE.md in each major package/directory with rules specific to that code. Claude Code uses the closest CLAUDE.md, so these override/supplement the root.
Examples:
src/services/CLAUDE.md -> "No UI imports, pure business logic, use async/await"
src/components/CLAUDE.md -> "All components need stories, 44pt touch targets"
src/models/CLAUDE.md -> "Never use auto key decoding, always explicit mapping"
src/utils/CLAUDE.md -> "Pure functions only, no side effects, document edge cases"
Keep each one 10-30 lines. Focus on:
docs/design-docs/
index.md -> List of design docs with status
core-beliefs.md -> 5-10 operating principles (the "why" behind your rules)
See references/core-beliefs-template.md for the template.
Examples of core beliefs:
docs/exec-plans/
index.md -> Links to active and completed plans
template.md -> Standard format for new plans
active/ -> Plans currently in progress
completed/ -> Archived plans (reference only)
See references/exec-plan-template.md for the template.
docs/golden-principles.md — Mechanical rules that prevent codebase drift. These are the "always/never" rules, not the "why" (that's core-beliefs).
See references/golden-principles-template.md for the template.
Key sections:
docs/generated/
db-schema.md -> Full schema dump (tables, columns, types, policies, triggers)
api-routes.md -> Auto-generated API route list (if applicable)
For databases: Use your ORM's schema dump, query information_schema, or use your database provider's tools. Include: columns with types/nullability/defaults, foreign keys, unique constraints, access policies, triggers, functions, indexes. Regenerate after each migration.
For APIs: Generate from OpenAPI spec, route definitions, or framework introspection.
docs/references/
[framework]-sdk.md -> Key SDK patterns for your main framework
[language]-patterns.md -> Language-specific patterns and gotchas
These are not copies of official docs. They're curated, minimal references covering only what your project uses. Think "cheat sheet for an agent working on this codebase."
Encode your "taste" (code style preferences) as lint rules with agent-friendly error messages. The error message should tell the agent what to do instead.
See references/lint-examples.md for examples across ESLint, Ruff, and SwiftLint.
When auditing existing docs (e.g., /lean-docs audit), scan the project against the 9-step checklist:
docs/ — do topic files exist? Are any >400 lines (need splitting)?docs/design-docs/core-beliefs.mddocs/golden-principles.md with GC cadencedocs/generated/ with auto-generated contentdocs/references/ with curated SDK docsUse these concrete steps rather than vague scans:
Read CLAUDE.md and count linesGlob "docs/**/*.md" to find existing topic filesGlob "**/CLAUDE.md" to find subdirectory CLAUDE.md filesGlob "docs/generated/*" for auto-generated contentGlob ".swiftlint.yml" or ".eslintrc*" or "ruff.toml" for lint configPresent results as a table:
| Step | Status | Notes |
|---|---|---|
| 1. CLAUDE.md | Pass/Needs work | [details] |
| ... | ... | ... |
Then offer to fix any gaps.
For a new repo, do these in order:
docs/ directorydocs/design-docs/core-beliefs.md (5-10 principles)docs/golden-principles.md with GC cadencedocs/generated/db-schema.md (or equivalent)docs/quality-grades.md