> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buttons.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent instructions

> How buttons init writes managed instruction blocks into CLAUDE.md, AGENTS.md, and other coding-agent files — and how the project button list stays current.

Buttons keeps two kinds of **managed markdown blocks** in your project's coding-agent files so any agent that opens the repo knows Buttons exists and what buttons are available. Both are written in place, wrapped in HTML-comment markers, and refreshed by the CLI — hand-edits *between* the markers are overwritten.

This is distinct from the hosted [skill.md](/ai/skill-md) (`npx skills add`): that installs a capability summary fetched from a URL; the blocks below are written **locally into your repo** by `buttons init` and by button mutations.

## 1. The instruction block — `buttons init --agent`

`buttons init --agent <target>` writes a Buttons instruction section into the file each coding agent reads, wrapped in `<!-- BUTTONS:START -->` / `<!-- BUTTONS:END -->` markers. Re-running `init` finds those markers and replaces the section in place, so your other content is never clobbered.

```bash theme={null}
buttons init --agent claude,agents-md    # non-interactive selection
buttons init --agent none                # skip the picker
buttons init                             # interactive picker on a TTY
```

Each target maps to the file that tool actually reads:

| Target (`--agent`) | File written                      | How                                                          |
| ------------------ | --------------------------------- | ------------------------------------------------------------ |
| `cursor`           | `.cursor/rules/buttons.mdc`       | Standalone MDC rule file (frontmatter + body), written whole |
| `claude`           | `CLAUDE.md`                       | `BUTTONS:START/END` section appended/updated in place        |
| `cline`            | `.clinerules`                     | `BUTTONS:START/END` section                                  |
| `copilot`          | `.github/copilot-instructions.md` | `BUTTONS:START/END` section                                  |
| `agents-md`        | `AGENTS.md`                       | `BUTTONS:START/END` section (cross-agent convention)         |
| `openclaw`         | `AGENTS.md`                       | `BUTTONS:START/END` section                                  |
| `hermes`           | `AGENTS.md`                       | `BUTTONS:START/END` section                                  |

<Note>
  Cursor is the exception: its `.mdc` file is standalone and rewritten whole. Every other target shares the `BUTTONS:START/END` contract, so the block is idempotent — safe to re-run and safe to sit next to your own instructions in the same file.
</Note>

`buttons init` also always writes a `.buttons/AGENTS.md` reference guide (Buttons' own onboarding doc for the folder) and a `.buttons/.gitignore`. That reference file belongs to Buttons and is overwritten on every `init`.

## 2. The button list — `## Buttons in this project`

Inside a project-local git repo, Buttons keeps a live list of the project's buttons in the repo-root `AGENTS.md`, wrapped in `<!-- BUTTONS:LIST:START -->` / `<!-- BUTTONS:LIST:END -->` markers. It's refreshed automatically after every button mutation — `buttons create`, `buttons delete`, `buttons add`, and `buttons import` — so an agent reading `AGENTS.md` always sees the current set without running a command first.

```markdown theme={null}
<!-- BUTTONS:LIST:START -->
## Buttons in this project

<!-- Auto-generated by the buttons CLI; edits between the markers are overwritten. -->

- `buttons press deploy` — Deploy a tagged release
- `buttons press summarize-pr` — Summarize an open PR
<!-- BUTTONS:LIST:END -->
```

Two behaviors worth knowing:

* **Press-ranked.** Buttons are ordered most-pressed-first (ties broken alphabetically for stable diffs), so the buttons an agent actually uses float to the top.
* **Capped at 20.** The 20 most-pressed buttons render with their descriptions; any beyond that collapse to a single comma-separated line pointing at `buttons list` for the full set. This keeps `AGENTS.md` scannable in workspaces with hundreds of buttons.

The refresh is best-effort and only runs for **project-local** buttons inside a **git repo** — it never fails the command that triggered it. As with the instruction block, don't hand-edit between the `BUTTONS:LIST` markers: the next mutation regenerates the block.

## Related

* [buttons init](/cli/buttons_init) — create the `.buttons/` dir and install instruction blocks
* [skill.md](/ai/skill-md) — the hosted `npx skills add` capability summary (a different mechanism)
* [Folder structure](/concepts/folder-structure) — where `.buttons/AGENTS.md` and per-button `AGENTS.md` live