deep-documentation

Deep Documentation

Use this skill when the task is to produce or maintain serious repository documentation, not a light README pass. The target quality bar is a repo where humans and LLMs can both understand how to use the system, what changed, and where to find the exact surface they need.

Documentation is part of delivery. If the code, API, setup, workflow, or behavior changes, the docs change in the same task.

Core rules

• Ground everything in the real repo. Read code, config, routes, schemas, tests, and existing docs before writing.
• Do not write vague marketing prose. Write operational, exact documentation.
• Keep the documentation layered: overview for orientation, guides for workflows, reference for exact interfaces, internals for maintainers.
• Use Mermaid diagrams in architectural documentation and anywhere business logic, workflow, or system behavior is easier to understand visually.
• Treat LLM-facing documentation as first-class project artifacts, not an afterthought.
• Treat changelog updates as required for meaningful changes.
• Create or update repo-local agent skills when the repo has distinct workflows or tool surfaces that future LLMs should follow.

Documentation standard

Documentation at this level should usually include most or all of these surfaces:

• README.md for the current product story, setup, quickstart, and top-level links.
• docs/README.md or equivalent index that maps the full documentation set.
• Guide pages for how to build, use, run, or operate the system.
• Reference pages for public APIs, endpoints, tools, config fields, schema shapes, environment variables, and commands.
• Internal architecture or subsystem pages for maintainers.
• Testing or verification docs when the repo has a meaningful test surface.
• Agent-skills documentation when the project wants LLMs to use the codebase in a specific way.
• llms.txt as the concise LLM index.
• llms-full.txt as the single-file documentation bundle for ingestion.
• CHANGELOG.md as the append-only historical record.