Skip to content
CAPA CAPA capa

Agent instructions

The agents section controls shared instruction files. capa writes to the instructions file each active provider reads: AGENTS.md for most providers, CLAUDE.md when claude-code is active, and so on: and never writes a file no active provider reads. AGENTS.md is the fallback when no active provider declares one.

When Gemini CLI shares AGENTS.md with another active provider, capa gives it a generated GEMINI.md with the same snippets, so rules targeted at other providers stay out of it. See Rules → Shared instruction files.

Base + additional

Section titled “Base + additional”
PieceBehavior
baseOptional full document. Written without capa markers; refreshed on each install
additionalList of snippets. Each wrapped in <!-- capa:start:id --> … <!-- capa:end:id -->
agents:
  base:
    type: github
    def:
      repo: acme/standards::docs/AGENTS.md
  additional:
    - id: deploy-notes
      type: inline
      content: |
        Prefer capa sh for deploy tools. Never paste secrets into chat.
    - id: team-local
      type: local
      path: ./docs/team-agents.md

Source types

Section titled “Source types”

Base can be:

  • ref: <url>: remote URL
  • type: github / gitlab with def.repo (@ or ::, optional pin)
  • type: local with path: file relative to the capabilities file (v2)

Additional snippets:

TypeFields
inlineid, content
remoteid, url
github / gitlabdef.repo (id optional)
localid, path

For git snippets, prefer owner/repo::path/to/file.md when you know the exact path.

Markers and cleanup

Section titled “Markers and cleanup”

capa upserts and prunes additional blocks by id on every capa install. Snippets keep their position on re-install, so they don’t drift below rule blocks folded into the same file. capa clean removes all capa-owned blocks; if a file becomes empty, capa deletes it.

Do not hand-edit inside <!-- capa:start:… --> markers if you want install to keep owning that snippet: change the capabilities file instead.

Section titled “Related”