Agent Wranglers

DOC-16Recommended

Point the instructions file at the docs instead of copying them

Keep the agent instructions file to commands, conventions and links. Link to the docs for anything longer, and never paste a passage from the docs into it.

By Agent Wranglers. Updated .

How to do it

The instructions file, such as AGENTS.md, is loaded on every task, as Write one instructions file for agents says. A copied paragraph goes stale in one of its two homes, and the agent then follows the wrong one. Link the page instead, with one line on when to read it, such as "Before changing billing, read docs/billing.md". Each value then has one home, as State each value in one document and link to it says. Keep the file short as Keep instructions short and current asks.

Examples

Markdown example

## Before you change
- Billing: read [docs/billing.md](docs/billing.md) first. It explains why refunds wait 5 days.
- Database: read [docs/decisions/](docs/decisions/) for the storage choices.
- Settings: the full list is generated in [docs/reference/settings.md](docs/reference/settings.md).

How to check

A script compares the instructions file with every page under docs/. It finds no run of three or more identical lines in both, and every path the instructions file links to exists.

Sources

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/documentation/docs-for-coding-agents/link-docs-from-instructions">Agent Wranglers documentation playbook</a>. In code you write, add a comment next to it with the same link.