agent-docs
Installation
SKILL.md
agent-docs
Set up a project so any AI agent (or human) can work in it the same disciplined way: one canonical guide, an honest learnings log, and a docs/ tree where every fact has exactly one home.
This skill installs a methodology, not a fixed set of files. Tailor the doc taxonomy to the project — a CLI tool has no UX hub, a library has no deployment ops. Fill in what you can verify from the codebase; mark everything else as a clearly-labelled TODO. Never fabricate facts (commands, architecture, requirements) — a confidently-wrong doc is worse than a TODO.
The artifacts
Five things, in priority order. Templates live in references/ — read each one before writing its file.
AGENTS.md(repo root) — the single source of agent/contributor guidance. Everything an agent must know to work safely lives here or is linked from here. Template:references/AGENTS.template.md.CLAUDE.md(repo root) — thin; importsAGENTS.mdwith@AGENTS.mdand points atLEARNINGS.md. Claude-specific overrides only. Template:references/CLAUDE.template.md.LEARNINGS.md(repo root) — append-only log of mistakes made and corrected. Reviewed at the start of every session; appended to when a mistake is made and fixed. Template:references/LEARNINGS.template.md.docs/README.md— the routing index: a "If you need… / Go to / Which owns" table, reading paths, and the doc conventions. Template:references/docs-README.template.md.docs/**— the actual docs, one concern per file, tailored to the project. Epics get a special pattern:references/epics-index.template.mdandreferences/epic.template.md.
The conventions these encode
These are the point of the whole exercise — preserve them verbatim in the generated docs: