auto-docs-skills / rules

---
description: Generate and maintain project documentation from the code (README, API reference, architecture notes, setup docs). Re-runnable to keep docs in sync as the code changes.
alwaysApply: false
---

# Auto Docs

A protocol for generating and maintaining project documentation from the code. Treat docs as derived from the codebase: generate them from what is actually there, regenerate the parts that drifted, and skip the parts that maintain themselves.

## 1. Analyze project structure

Read the project before writing anything.

- Detect project type from manifests (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`).
- Identify entry points and the public surface: exports, routes, CLI commands, config keys, environment variables.
- Locate existing docs and the install, build, test, and start commands.

Do not document what you have not read.

## 2. Generate or update the README

Answer four questions in order: what is this, how do I run it, how do I use it, where do I go next. Update drifted sections; leave hand-tuned prose alone.

## 3. Generate the API reference

For each public export, route, or command: name and signature, one-sentence purpose, parameters with types, return shape, a real usage example, and known errors. Document the public surface; skip private helpers.

## 4. Write architecture notes

For any non-trivial system: component responsibilities, data flow, relationships as a list or markdown diagram, and the non-obvious design decisions with the constraint behind each.

## 5. Write setup docs

Prerequisites, step-by-step install, an environment-variable table (name, controls, required, example, never a real secret), and how to verify it worked.

## 6. Keep docs in sync with code

On re-run, diff the code surface against what the docs describe. Regenerate the sections whose source changed, leave the rest, and flag docs that reference code that no longer exists.

## What to document vs skip

Document the public API, how to install and run, architecture and data flow, and non-obvious design decisions. Skip private helpers, self-evident code, generated files, and prose that restates a function name.

## On committing

Write the files and summarize what changed. Let the human decide when to commit; do not auto-commit unless asked.