> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ankra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Teach Your Agents with AGENTS.md

> Per-add-on and per-manifest AGENTS.md documents capture operational learnings that teammates and Ankra's AI read and write.

Every manifest and add-on in a Stack can carry an optional **AGENTS.md** - a markdown document of operational learnings for that one component: upgrade gotchas, safe rollout order, values that must stay pinned. Teammates and Ankra's AI accumulate knowledge there over time, so the next person (or agent) touching the component starts from what the last one learned.

AGENTS.md is deliberately narrow: it belongs to a single add-on or manifest and travels with it in the GitOps repository. For organisation-wide conventions that apply to every conversation, use [AI Skills](/platform/ai-skills) instead - skills are org-scoped instructions, AGENTS.md is per-resource learnings.

## Where the Files Live

Ankra writes each document as a sibling file next to the component it describes, in the connected GitOps repository:

```
clusters/<cluster-name>-<short-id>/
└── stacks/<stack-name>/
    ├── README.md                      # the Stack's description
    ├── add-ons/
    │   └── <addon-name>/
    │       ├── values.yaml
    │       └── AGENTS.md              # learnings for this add-on
    └── manifests/
        ├── <manifest-name>.yaml
        └── <manifest-name>.AGENTS.md  # learnings for this manifest
```

This mirrors how a Stack's `description` becomes `README.md`: the main IaC document carries only an `agents_md_from_file` pointer, never the content itself, so the markdown stays readable and diffable in Git.

## Authoring

There are three equivalent ways to write an AGENTS.md, and they converge on the same sibling file:

* **Portal** - every add-on and manifest panel in the Stack Builder has an **AGENTS.md** tab with a markdown editor and preview.
* **IaC YAML** - set `agents_md` (inline markdown) or `agents_md_from_file` (repo-relative path) on the entry in your [ImportCluster](/reference/importcluster) definition. Inline content is normalised to a sibling file on the next platform push.
* **Git** - commit an AGENTS.md file directly in the GitOps repository and reference it with `agents_md_from_file`.

```yaml theme={null}
addons:
  - name: fluent-bit
    chart_name: fluent-bit
    chart_version: 0.49.1
    repository_url: https://fluent.github.io/helm-charts
    namespace: fluent-bit
    agents_md: |-
      # fluent-bit learnings
      - Keep `service.enabled: true` - the health checks depend on it.
      - Upgrade one minor version at a time; jumping 0.48 to 0.50 broke parsers.
```

## Semantics

| Behaviour        | Detail                                                                                         |
| ---------------- | ---------------------------------------------------------------------------------------------- |
| Omit the field   | The stored document is preserved unchanged                                                     |
| Empty string     | Clears the document - the file is removed from the GitOps repository on the next reconcile     |
| Edit the content | Never triggers a redeploy of the resource - AGENTS.md is documentation-only and deploy-neutral |
| GitOps conflicts | AGENTS.md edits auto-merge rather than conflicting with body edits                             |
| Encryption       | Content is plaintext in the Git repository - it is never SOPS-encrypted                        |

<Warning>
  AGENTS.md is stored as plaintext in your Git repository and is shown to AI agents. Never put credentials, tokens, or other secrets in it - use [SOPS](/guides/sops) encrypted values or Kubernetes Secrets for sensitive data.
</Warning>

## How Ankra's AI Uses It

Ankra's AI - the [AI Assistant](/platform/ai-assistant), agents, and [MCP clients](/platform/mcp-server) - reads AGENTS.md wherever it reads the Stack: `get_stack_details` returns each component's document, and `export_cluster_iac` includes it in the exported IaC. When the AI learns something worth keeping - a flag that must stay pinned, an upgrade that needs a manual step - it can write that learning back through the `create_stack` and `update_stack` tools' `agents_md` field, so the knowledge persists beyond the conversation.

## Related

* [ImportCluster YAML Schema](/reference/importcluster) - the `agents_md` and `agents_md_from_file` fields
* [GitOps](/concepts/gitops) - how the repository is structured and synced
* [AI Skills](/platform/ai-skills) - organisation-wide AI instructions