Skip to content
Canon

Skill · meta · agents-md

Write AGENTS.md

Write or audit AGENTS.md — the repo constitution for coding agents. Use when setting up a coding agent, adding project instructions, defining done, pointing at skills, or the user mentions AGENTS.md, CLAUDE.md, copilot-instructions, .cursorrules, or 'how should the agent work in this repo'.

GET /api/canon/skills/agents-md?format=md

AGENTS.md is always in the window. Skills are not. Put commands, boundaries, and done here. Put depth in skills. If the agent cannot run the commands, they are decoration.

When

A coding agent will touch this repository. The constitution is short, true, and runnable.

Do

  1. 01

    Commands that actually run

    Install, test, typecheck, build — the exact invocations. Nested AGENTS.md override locally; one root file is the default.

  2. 02

    Boundaries

    Main, secrets, prod, what never to do. Short. True. The repo itself must follow them.

  3. 03

    Point at skills

    Do not paste a UI treatise or a 12-factor essay. Link the skill that should load.

  4. 04

    Define done

    Reviewable PR + tests green + human gate on deploy. Done is not a sentence from the model.

Don't

  • Paste every style nit. That is a skill.
  • List commands the Makefile does not implement.
  • Keep secrets, tokens, or staging URLs in the constitution.

Hard rules

  • One root AGENTS.md. Nested files override in their tree.
  • The harness must be able to execute every command named.
  • Constitution points; skills teach; evals score.

AGENTS.md

markdown
# AGENTS.md

## Commands
- Install: `npm ci`
- Test: `npm test`
- Typecheck: `npm run typecheck`
- Build: `npm run build`

## Rules
- Do not force-push to main.
- Secrets live in the platform env, never in the repo, never in prompts.
- Prefer the smallest diff that makes tests pass.
- After code changes, run typecheck and tests. Compact the failure.

## Skills
Load the matching skill before restyling UI or designing agents.

## Done
Reviewable PR + tests green + human gate on deploy.

Refuse

  • No verifier in the loop — The agent writes code and declares victory. Tests, typecheck, and build are optional.
  • Unowned prompt — The policy lives in a framework black box you cannot diff, test, or revert.

Load with this

Job · Coding agentJob · Skill packPlaybook · Write AGENTS.mdAGENTS.md as ConstitutionOwn Your PromptsVerification as Architecture

Load next

Trigger tests

Should fire

  • “Write AGENTS.md for this repo”
  • “What should we put in CLAUDE.md?”
  • “Add project instructions for the coding agent”

Should not

  • “Write a product README”
  • “Document the public API”