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). Why there are three ways and not one: reasoning.

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 <unit>-<skill>, unless the skill's name already starts with <unit>-; 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).

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)	`.claude/skills` (skills)
Codex CLI	From the root down to the working directory, at start, up to 32 KiB together (docs)	`.agents/skills`; the list of skills is cut at 2 % of the context or 8,000 characters (docs)
GitHub Copilot	Anywhere in the repository; the nearest file takes precedence (docs)	`.agents/skills`, `.claude/skills` (docs)
Kiro	Not mentioned in its documentation of skills	Not reached: it reads `.kiro/skills` only (docs)
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).
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#

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.
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.
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.

This page as plain Markdown, and its source on GitHub.