Skip to main content
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 (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. 
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 writtenHow
cursor.cursor/rules/buttons.mdcStandalone MDC rule file (frontmatter + body), written whole
claudeCLAUDE.mdBUTTONS:START/END section appended/updated in place
cline.clinerulesBUTTONS:START/END section
copilot.github/copilot-instructions.mdBUTTONS:START/END section
agents-mdAGENTS.mdBUTTONS:START/END section (cross-agent convention)
openclawAGENTS.mdBUTTONS:START/END section
hermesAGENTS.mdBUTTONS:START/END section
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.
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. 
<!-- 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.
  • buttons init — create the .buttons/ dir and install instruction blocks
  • skill.md — the hosted npx skills add capability summary (a different mechanism)
  • Folder structure — where .buttons/AGENTS.md and per-button AGENTS.md live