What each project-instruction file should do

design.md, AGENTS.md, and SKILL.md are easy to merge into one long prompt. The tool then carries the wrong part into every task. design.md holds visual decisions and the checks that protect them. AGENTS.md, in the tools that read it, holds project rules that should be present while the agent works in that repository. SKILL.md holds a procedure the agent should open only when the task matches, not on every unrelated edit. Harbor Ledger's rule 'do not change the published prices' belongs in the project instructions if every task must respect it. The steps for reviewing a phone layout belong in a skill, because a copy edit does not need them.

Nothing in the Agent Skills specification, the Codex AGENTS.md guide, or the Claude Code memory guide says that a file named design.md is loaded automatically. Vercel publishes one at a URL and tells agents to read it. That is a convention you opt into. If your design.md sits unread, the agent is not disobeying a universal standard. You have not put the file on a path that tool reads. Link it from the instruction file that tool does read, or add the filename where that tool allows fallback names.

Each tool looks for project instructions in a slightly different way. Keep one short source-of-truth file, then point each tool to it using the file it already knows how to read. Codex starts with the user-level instructions, then walks from the project root to the folder where you are working. It takes at most one instruction file from each folder and gives the closest file the last word. The default project-document limit is 32 KiB, measured in bytes. Claude Code reads CLAUDE.md. Some versions can fall back to AGENTS.md when no CLAUDE.md is on the path, but that depends on the installed version and session type. Record the client and version when the exact lookup order matters.

A skill is a folder the tool should open for one kind of task, not on every edit. The Agent Skills specification says the folder name must match the name written at the top of SKILL.md, and that file must also say what the skill does and when to use it. Tools are expected to see that name and description first, then read the instructions when the skill is used, and read extra files only when needed. Claude Code's docs use that pattern and add fields that other tools may ignore. A design review skill should say when to use it, such as 'review a rendered page at desktop and phone widths,' and when not to, such as 'a request to rewrite a headline only.' A description that says 'helps with design' will open on the wrong tasks, or never open.

The rule is: the primary call to action on marketing pages says 'Book a 20-minute call' and uses the existing button component. In design.md it sits beside the button's visual rules, because it is about that component's job. In AGENTS.md or CLAUDE.md it sits as a one-line project rule if every edit must preserve it. In SKILL.md it appears inside the review procedure as a check, not as the only copy of the rule. If you put the whole design essay in AGENTS.md, you can exhaust Codex's 32 KiB project-document limit and bury the price rule. If you put the price rule only in a skill, a task that never loads the skill can change the price.

Give each source a distinct job. Customer facts and approved content win for claims, names, prices, and policies. The current product behaviour shows what the page actually does. design.md states the intended visual and interaction rules. If the implementation breaks an approved rule, change the implementation; do not rewrite the rule merely to describe the mistake. A skill's examples come last and can become stale. Do not rely on a tool to notice that an example still says $49 after you changed the offer.