Skip to main content
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 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:
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 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.

​
Semantics

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 encrypted values or Kubernetes Secrets for sensitive data.

​
How Ankra’s AI Uses It

Ankra’s AI - the AI Assistant, agents, and MCP clients - 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.