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.

  1. 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.
  2. CLAUDE.md (repo root) — thin; imports AGENTS.md with @AGENTS.md and points at LEARNINGS.md. Claude-specific overrides only. Template: references/CLAUDE.template.md.
  3. 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.
  4. 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.
  5. docs/** — the actual docs, one concern per file, tailored to the project. Epics get a special pattern: references/epics-index.template.md and references/epic.template.md.

The conventions these encode

These are the point of the whole exercise — preserve them verbatim in the generated docs:

Installs
1
First Seen
Jul 21, 2026