# Coding agents How a coding agent learns that a repository uses unifold, what it reads, and what it must not trust. ## Three ways in | Way | What it is | When the agent sees it | |---|---|---| | `AGENTS.md` | A generated file per unit: a pointer to `README.md`, the documents of the unit by kind, its skills. The root file also carries the unifold block: what unifold is, the commands `show`, `capability` and `check`, and an index of the units below the root (name, path, responsibility, and the status when it is not `active`) when there are at most 40 of them, otherwise a pointer to `unifold tree` | Always, where the agent loads `AGENTS.md` | | The skills | `unifold-convert`, the procedure that brings a repository into the format, and `unifold`, the procedures for reading and changing a unifold project | When the agent decides that the task calls for it | | The tool | `unifold show`, `capability`, `impact` and `check`, each with `--json` | When the agent runs it | `unifold init --agents` sets up all three: it installs the skills and the tool in `docs/skills/` of the root, writes the stubs described below, and points the block in the root `AGENTS.md` at them ([tool.md](tool.md#init)). Why there are three ways and not one: [reasoning](../explanation/reasoning.md#why-three-ways-in-for-agents). ## Where skills are found No agent searches `docs/skills/`. unifold keeps skills there, next to the code they concern, and `unifold skills sync` writes a generated stub for each into `.agents/skills/` and `.claude/skills/` at the root. The stub of a skill of the root unit keeps the name of the skill, for example `unifold`. The stub of a skill of another unit is named `-`, unless the skill's name already starts with `-`; if two units would get the same name, the path of the unit with `-` for `/` takes the place of its name. A stub has the description of the skill, and its body says which file to read. Stubs are files, not symbolic links, so that they work on every operating system and relative links in the skill stay valid. Commit them. The checker reports stale stubs when the folders exist. `.agents/skills` is the folder that the Agent Skills project recommends to all clients ([source](https://agentskills.io/client-implementation/adding-skills-support.md)). ## What each agent reads The agents whose behaviour leads to a consequence below, as their documentation said on 2026-10-25. Other agents that read `AGENTS.md` and search `.agents/skills` or `.claude/skills` are reached the same way. | Agent | `AGENTS.md` | Folder in which it finds the stubs | |---|---|---| | Claude Code | Read natively since v2.1.277, but only if no `CLAUDE.md` or `CLAUDE.local.md` exists at or above the working directory; otherwise `CLAUDE.md` has to import it with `@AGENTS.md` ([memory](https://code.claude.com/docs/en/memory)) | `.claude/skills` ([skills](https://code.claude.com/docs/en/skills)) | | Codex CLI | From the root down to the working directory, at start, up to 32 KiB together ([docs](https://learn.chatgpt.com/docs/agent-configuration/agents-md)) | `.agents/skills`; the list of skills is cut at 2 % of the context or 8,000 characters ([docs](https://learn.chatgpt.com/docs/build-skills)) | | GitHub Copilot | Anywhere in the repository; the nearest file takes precedence ([docs](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions)) | `.agents/skills`, `.claude/skills` ([docs](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills)) | | Kiro | Not mentioned in its documentation of skills | Not reached: it reads `.kiro/skills` only ([docs](https://kiro.dev/docs/skills/)) | | Aider | Nothing is loaded automatically | No skills | Consequences: - `unifold init --agents` prints a hint when a `CLAUDE.md` exists that does not mention `AGENTS.md`. - Copilot may use only the nearest `AGENTS.md`. Every unit's `AGENTS.md` therefore carries the one line "unifold unit; run `unifold show` here." - Codex stops loading at 32 KiB. The generated `AGENTS.md` is therefore short: pointers, not text ([documents.md](documents.md)). - Every agent in the table can run a shell command. The tool is the one way in that works for all of them. ## What the agent reads, in order 1. The `AGENTS.md` files that its harness loads, and the `README.md` each of them points to. Its `## Why` is what cannot be derived from code. 2. `unifold show` in the folder of the task. It prints the unit, its capabilities and needs, who finally provides and uses them, the status of every unit it mentions, and the skills and decisions of the unit. 3. Only then further files: `docs/explanation/context.md`, a contract, the explanation file the task needs. The `unifold` skill has the table of what to read for which task. `unifold impact` answers "what is affected if I change this": the units that depend on a unit or capability, through the whole tree, and the context items that cite its files. ## What an agent must not take as fact | Sign | Meaning | |---|---| | `status: planned` | The text describes an intention. The code may not exist. | | A decision with `status: proposed` | Nobody has agreed to it yet. Only accepted and derived decisions bind. | | A warning about a stamp | A restatement in `docs/explanation/context.md` may no longer match its source. Read the source. | | `responsibility: TODO`, `summary: TODO` | A placeholder that nobody has completed. | | Decision with `status: derived` | A source settles it, says the author. Whether the passage says so is a review question. | `show` and `capability` print the status of every unit they mention and mark planned units and proposed decisions. ## Hooks An agent runs `unifold check` when it stops, not after every edit: a unit that is being added is broken for a moment. The hook for Claude Code, a pre-commit hook and a CI job are in [tool.md](tool.md#hooks-and-continuous-integration).