Skip to content
CAPA CAPA CAPA Docs

Agent instructions

The agents section controls shared instruction files. capa always manages AGENTS.md. When claude-code is among your providers, it also manages CLAUDE.md.

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. 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”