A PR and commit block in AGENTS.md is the short section that tells a coding agent how to package its work: which branch to work on, how to write commit messages, what a pull request description must contain, which checks to run before opening the PR, and which steps always wait for a human, such as force-pushing or merging. The agents.md site lists "commit messages or pull request guidelines" among the extra instructions that belong in the file, and its sample AGENTS.md has a "PR instructions" section. Treat the block as a contract you write down, not a feature a tool enforces: the agent reads it as guidance, and your repo settings and reviewers still do the enforcing.
Who this is for
Your agent writes decent code but opens PRs with vague titles, one giant commit, or no record of whether the tests ran. You want those habits fixed in one place every agent reads.
What the block should cover
| Topic | What to write | Example line |
|---|---|---|
| Branches | Where work happens and how branches are named | "Work on a new branch named `agent/<short-topic>`; never commit to `main`." |
| Commit messages | Your team's format and what one commit covers | "One logical change per commit. Subject line in the imperative, under ~72 characters." |
| PR title | The format you want | agents.md's sample: "Title format: [<project_name>] <Title>" |
| PR description | Sections the description must include | "Include: what changed, why, how it was verified, and anything left undone." |
| Checks before the PR | When to run verify, pointing to where it's defined | "Run the verify commands in `## Verify` before every commit; don't open a PR on a red run." |
| Human-only steps | What the agent must stop and ask about | "Never force-push. Never merge. Ask before rebasing a branch someone else has pushed to." |
The commit format is your choice. If your team uses Conventional Commits, say so and give one example; AGENTS.md doesn't require any particular style.
A sample block
## PR and commit instructions
- Branch: create `agent/<short-topic>` from `main`. Never commit directly to `main`.
- Commits: one logical change each. Imperative subject line, e.g. "Add retry to webhook handler".
- Before committing: run the commands in `## Verify` (`pnpm lint` and `pnpm test` here). Fix failures first.
- PR title: `[<package>] <Title>`.
- PR description: what changed, why, how you verified it, and open questions.
- Stop and ask a human before: force-pushing, merging, deleting branches, or changing CI config.
- Never put secrets in commits or PR text. Use placeholders like `API_KEY=your-key-here`.Swap in your own commands. The `pnpm lint` and `pnpm test` pair mirrors the agents.md sample, which says "Always run `pnpm lint` and `pnpm test` before committing."
Keep verify and PR rules separate
Define the checks once, in a verify section: the exact commands and what passing means. The PR block then says *when* to run them and how to package the result. If the commands change, you update one place, and the PR block doesn't drift out of date.
Nested files and per-package rules
agents.md says agents read the nearest AGENTS.md in the directory tree and the closest one takes precedence. A package with its own release process can carry its own PR block. Keep shared rules (branches, human-only steps) at the root, and put only what's different in the package file.
Pitfalls
- Assuming the file enforces anything. An instruction is not a guardrail. Back "never force-push" and "never merge" with branch protection and required reviews in your Git host.
- Copying the verify commands into the PR block. They drift. Point to the verify section instead.
- Rules nobody can check. "Write good commits" gives the agent nothing to follow. Name the format and give one example.
- Inventing required headings. agents.md has no required fields. Use headings your team actually reads.
How to check it
- Give the agent a small, real change and ask it to take it all the way to a PR.
- Check the branch name, the commit messages, and the PR title against the block.
- Confirm the PR description says how the change was verified.
- Confirm it stopped and asked rather than merging or force-pushing.
- In a package with its own AGENTS.md, repeat once and confirm the package rules were applied.
For what else belongs in the file, see the AGENTS.md guide for Cursor, Claude Code, and Codex. For the secrets line in the sample block, see the AGENTS.md secrets block.
Where ShipKits fits
The Operator Pack ($47) is markdown seats + skills + install.sh — not a hosted app, not a chatbot. Seven named seats, three skills, an ops playbook and a token-cost playbook. Done means a file, PR, or URL. Its AGENTS.md templates include branch, commit, and PR sections plus a human-approval list you can edit to match your repo. Soft path: start at /free. Cheat Sheet for the skim checklist mindset.
Soft next step
Add a six-line PR and commit block to your root AGENTS.md today, then run one real change through it. Soft ladder: /free, then the Operator Pack ($47). Related: AGENTS.md guide, verify step, secrets block.