How to Write AI Context Files in Plain Text and Markdown
Quick Answer
An AI context file is a plain-text or Markdown file that gives an assistant durable background about a project, so it stops guessing. Conventions, commands, decisions, anything you'd otherwise re-explain every session. Three shapes come up most: AGENTS.md for cross-tool coding-agent instructions, CLAUDE.md for Claude Code specifically, and llms.txt for a discovery map published at a site's root. None of them need a special editor or a database — they're ordinary Markdown, which is exactly why they've spread so fast.
How It Actually Works
Why plain text and Markdown, not a database or a wiki
A context file has to survive being read by more than one tool, diffed in version control, and skimmed by a person at 2am. Plain text and Markdown do all three, no export step, no proprietary format standing between the content and whoever's reading it — human or model.
The common formats: AGENTS.md, llms.txt, CLAUDE.md
AGENTS.md is a plain-Markdown file at a repo's root with no required schema. It was formalized as an open specification in 2025, and more than 20 coding tools now read it natively. A minimal one looks like this:
# AGENTS.md
## Setup
npm install
## Test
npm test
## Style
Two-space indent. No default exports.llms.txt solves a different problem. It's published at /llms.txt on a site so an agent can find a curated index instead of crawling raw HTML. The spec requires a single H1 with the project name, an optional summary, and zero or more H2-delimited sections listing links — closer to a table of contents than a set of instructions. CLAUDE.md and similar tool-specific files sit alongside these two, and each targets a different audience and a different job: AGENTS.md and CLAUDE.md give instructions, llms.txt helps a tool find content. It's the same instinct behind how AI coding assistants read a project's other plain-text files — the more a repo is already organized in readable text, the less a context file has to repeat.
How agents find these files
Most tools use hierarchical discovery: scan from the current working directory upward, and stack what they find across tiers instead of letting one file replace another. A repo-root AGENTS.md and a subfolder-specific one can both apply at once, with the more specific file adding detail rather than overriding everything above it. None of that works if the Markdown itself is inconsistent, which is why the same formatting discipline that keeps technical docs readable is what keeps a context file parsing the same way across every tool that reads it.
When to Use It (and When to Skip It)
Building your own, one small file at a time
Skip the single sprawling document. A short, single-purpose file per concern — build commands in one place, style rules in another, a running decision log in a third — stays useful precisely because each one answers one question well. It's the same reasoning behind a CONTRIBUTING.md people actually follow and a CHANGELOG.md worth reading: small, focused, root-level Markdown files that don't try to be everything at once.
What belongs in it — and what never does
Include conventions, commands, durable decisions, and style notes — anything the assistant shouldn't have to guess twice. Never include API keys, passwords, or tokens. A context file is often committed to source control and read by more than one tool, so treat it the way you'd treat any file a stranger could open, and keep credentials in a secrets manager instead.
When a context file isn't worth it
A one-off script, or a project nobody else — human or agent — will touch again, doesn't need one. A short code comment does the same job with less overhead. Add a context file once the repeated cost of re-explaining something starts to add up, not before.
Frequently Asked Questions
What is an AI context file?
A plain-text or Markdown file — AGENTS.md, CLAUDE.md, llms.txt, or a hand-rolled equivalent — that gives an AI assistant durable background about a project or workflow: conventions, commands, decisions, or content it shouldn't have to guess or re-derive every session.
Do I need YAML frontmatter in an AI context file?
No. AGENTS.md and llms.txt both work as plain Markdown with no required schema. Some tools layer optional YAML frontmatter on top to scope a file to certain paths or roles, but the body itself stays ordinary prose and headings.
What's the difference between AGENTS.md and llms.txt?
AGENTS.md is an instruction file — it tells a coding agent how to build, test, and work in your repo. llms.txt is a discovery file — it's published at a site's root so an agent can find a curated map of pages instead of crawling raw HTML. One's for doing work; the other's for finding content.
Should I put secrets in a context file?
Never. API keys, passwords, and tokens don't belong in AGENTS.md, CLAUDE.md, or any Markdown context file — those files are often committed to source control or read by multiple tools. Keep credentials in a secrets manager and reference them by name only.
How long should an AI context file be?
Short enough to stay useful in every prompt. A few tight, well-organized sections beat one sprawling file. Split by concern if a single file gets unwieldy, and prune anything the assistant hasn't actually needed.
How Carets Fits In
AI context files are exactly the file type Carets is built to handle well: plain Markdown, meant to be written and read quickly, with no formatting to fight. Carets is a native notes and code editor for iPhone, iPad, and Mac that renders standard Markdown as you write it, so an AGENTS.md or llms.txt file looks the same in Carets as it does anywhere else that reads it.
Keeping several context files straight — a build-commands file, a style file, a decision log — is easier with files, projects, and tags to group them, instead of loose documents scattered across folders. And because Carets keeps everything in plain text, none of it is locked into a format only one app can open. A context file you write in Carets works everywhere your tools expect it to.
Carets is available on the App Store for iPhone, iPad, and Mac.