Agent Instructions

The agents section of your capabilities file lets CAPA manage AGENTS.md and CLAUDE.md in your project root — the standard files that AI coding agents read for project-specific instructions.

Why AGENTS.md?

AGENTS.md is an open format (stewarded by the Agentic AI Foundation under the Linux Foundation) supported by Cursor, OpenAI Codex, Google Jules, Amp, Warp, GitHub Copilot, and many more. Think of it as a README for agents — a dedicated, predictable place for build steps, conventions, and context that agents need but that would clutter a README.

CLAUDE.md is the equivalent file read by Claude Code (Anthropic) for persistent project memory. CAPA writes both files automatically when both agent types are configured as providers.

Which Files Are Created

CAPA determines target files automatically from the providers list:

Providers include Files written
cursor only (or any non-Claude provider) AGENTS.md
claude-code (or any claude* provider) AGENTS.md and CLAUDE.md

Both files receive identical content. AGENTS.md is always written because it is the universal format; CLAUDE.md is additionally written so Claude Code picks up the same instructions.

How CAPA Tracks Ownership

Each snippet CAPA writes is wrapped in HTML comment markers that are invisible in rendered markdown and largely ignored by LLMs (very low token cost):

<!-- capa:start:my_snippet_id -->
Content of the snippet goes here.
<!-- capa:end:my_snippet_id -->
  • Install: upserts every snippet (adds if missing, replaces if changed) and prunes any capa-owned blocks whose id is no longer in the capabilities file.
  • Clean: strips all capa-owned blocks. If the file is empty after stripping, it is deleted.
  • The base content is written directly without markers — it is not modified on clean.
  • Content you write outside capa markers is never touched (when no base is configured).
  • The same security checks (options.security.blockedPhrases, options.security.allowedCharacters) that apply to skills are also applied to all agent snippet content.

Configuration

Base File (optional)

The base seeds your agent instructions file with content from a remote source. When a base is configured, capa install always re-downloads it and rebuilds the file from scratch (base content + snippets). Supported source types mirror the skill system:

agents:
  # Remote URL
  base:
    ref: https://raw.githubusercontent.com/org/repo/main/AGENTS.md

  # GitHub file (owner/repo@filepath)
  # base:
  #   type: github
  #   def:
  #     repo: org/repo@AGENTS.md

  # GitHub file pinned to a version tag
  # base:
  #   type: github
  #   def:
  #     repo: org/repo@AGENTS.md:v1.2.0

  # GitLab file pinned to a commit SHA
  # base:
  #   type: gitlab
  #   def:
  #     repo: group/repo@AGENTS.md#abc123def
{
  "agents": {
    "base": {
      "ref": "https://raw.githubusercontent.com/org/repo/main/AGENTS.md"
    }
  }
}

Additional Snippets

The additional list defines snippets that are appended after the base (or directly into the file when no base is set). Each snippet supports four source types:

inline — literal text in the YAML

agents:
  additional:
    - type: inline
      id: setup_tools
      content: |
        ## Agent Setup
        After learning a new skill, call the setup_tools tool,
        then use call_tool to invoke the relevant tool.
{
  "agents": {
    "additional": [
      {
        "type": "inline",
        "id": "setup_tools",
        "content": "## Agent Setup\nAfter learning a new skill, call the setup_tools tool."
      }
    ]
  }
}

remote — fetched from a raw URL

agents:
  additional:
    - type: remote
      id: ci_tips
      url: https://raw.githubusercontent.com/org/repo/main/agent-tips.md
{
  "agents": {
    "additional": [
      {
        "type": "remote",
        "id": "ci_tips",
        "url": "https://raw.githubusercontent.com/org/repo/main/agent-tips.md"
      }
    ]
  }
}

github / gitlab — file from a repository

Uses the same owner/repo@filepath format as skills, with optional :version or #sha pinning. The id is optional and is derived from the filepath if omitted (e.g. AGENTS.md → AGENTS_md).

agents:
  additional:
    # Fetch from GitHub, id derived from filename → "AGENTS_md"
    - type: github
      def:
        repo: org/shared-standards@AGENTS.md

    # Fetch from GitHub, explicit id, pinned to a tag
    - type: github
      id: pinned_tips
      def:
        repo: org/repo@docs/agent-tips.md:v2.1.0

    # Fetch from GitLab, pinned to a commit SHA
    - type: gitlab
      def:
        repo: group/repo@AGENTS.md#abc123def
{
  "agents": {
    "additional": [
      {
        "type": "github",
        "def": { "repo": "org/shared-standards@AGENTS.md" }
      },
      {
        "type": "github",
        "id": "pinned_tips",
        "def": { "repo": "org/repo@docs/agent-tips.md:v2.1.0" }
      },
      {
        "type": "gitlab",
        "def": { "repo": "group/repo@AGENTS.md#abc123def" }
      }
    ]
  }
}

repo string format

Part Description
owner/repo GitHub or GitLab repository path (supports nested GitLab groups)
@filepath Path to the file inside the repository, e.g. AGENTS.md or docs/tips.md
:version Optional version tag to pin to, e.g. :v1.2.0
#sha Optional commit SHA to pin to, e.g. #abc123def

When no version or SHA is specified, CAPA fetches from HEAD (the default branch).

Full Example

providers:
  - cursor
  - claude-code   # triggers CLAUDE.md creation in addition to AGENTS.md

agents:
  base:
    type: github
    def:
      repo: org/shared-standards@AGENTS.md   # seeds both files with shared content
  additional:
    - type: inline
      id: setup_tools
      content: |
        ## Agent Setup
        After learning a new skill, call the `setup_tools` tool,
        then use `call_tool` to invoke the relevant tool.
    - type: github
      id: ci_tips
      def:
        repo: org/repo@docs/ci-agent-tips.md:v1.0.0

skills:
  - id: capabilities-manager
    type: github
    def:
      repo: infragate/capa@capabilities-manager
{
  "providers": ["cursor", "claude-code"],
  "agents": {
    "base": {
      "type": "github",
      "def": { "repo": "org/shared-standards@AGENTS.md" }
    },
    "additional": [
      {
        "type": "inline",
        "id": "setup_tools",
        "content": "## Agent Setup\nAfter learning a new skill, call the setup_tools tool."
      },
      {
        "type": "github",
        "id": "ci_tips",
        "def": { "repo": "org/repo@docs/ci-agent-tips.md:v1.0.0" }
      }
    ]
  },
  "skills": [
    {
      "id": "capabilities-manager",
      "type": "github",
      "def": { "repo": "infragate/capa@capabilities-manager" }
    }
  ]
}

Running capa install with the above (with both cursor and claude-code in providers) produces both AGENTS.md and CLAUDE.md with this structure:

# Shared Standards
…(content from base GitHub file, written as-is)…

<!-- capa:start:setup_tools -->
## Agent Setup
After learning a new skill, call the `setup_tools` tool,
then use `call_tool` to invoke the relevant tool.
<!-- capa:end:setup_tools -->

<!-- capa:start:ci_tips -->
…(content from ci-agent-tips.md)…
<!-- capa:end:ci_tips -->

Syncing Changes

Re-run capa install after any change to the agents section:

  • Added snippets are appended.
  • Changed snippet content is updated in place.
  • Removed snippet ids are pruned from the file.
  • When a base is configured, the file is fully rebuilt from the freshly downloaded base content plus current snippets.

Related Documentation