Structured Agent Files Should Own Detail. AGENTS.md Should Stay Portable.

APC works best when it does two jobs at once without mixing them.

First job: give every tool one obvious project entrypoint. That is AGENTS.md at the repo root.

Second job: give APC-aware tools a cleaner place for structured detail. That is .apc/agents/<slug>.md next to .apc/project.json.

That split matters because compatibility and structure are not the same problem.

In the APC companion spec for AGENTS.md, the root file is defined as the compatibility-facing contract for agent discovery. It lives at the project root, next to .apc/, and many tools already know how to find and read it. The same spec also says that when .apc/agents/<slug>.md exists for the same slug, that structured file should be treated as the authoritative structured definition.

That is the right boundary.

If you try to put every detail into AGENTS.md, the root contract becomes noisy. Long descriptions, custom fields, memory overrides, skill lists, and formatting edge cases all end up in the one file every runtime has to scan first. Portable discovery gets harder exactly because the “simple entrypoint” started acting like a database.

If you go the other way and drop AGENTS.md entirely, portability gets worse. A lot of tools can walk up a repo and look for one familiar root file. Fewer tools know your internal structured layout on day one.

APC avoids that tradeoff by keeping both layers.

A small root contract can look like this:

# Agents

## reviewer
- **Role**: Code review
- **Model**: gpt-5
- **Skills**: documentation
- **Description**: Reviews risks, tests, and regressions.

That is enough for discovery, routing, and a first-pass understanding of the project.

Then the richer definition can live where APC-aware tooling expects it:

.apc/
  project.json
  agents/
    reviewer.md

This also matches how APX uses the project.

APX reads AGENTS.md as project guidance at runtime. In buildProjectAgentsBlock, it loads the root file, truncates it if needed, and injects it into the prompt as “Project guidance (AGENTS.md)”. That is a strong hint about intended size and purpose: useful startup rules, not an ever-growing dump of agent internals.

APX also has a dedicated parser for AGENTS.md sections. It looks for one # Agents heading, reads each ## <slug> block, and extracts bullet fields like Role, Model, Skills, and Description. That parser exists because the root contract needs to stay predictable and portable.

So the practical rule is simple:

• Put cross-tool discovery in AGENTS.md.
• Put structured per-agent detail in .apc/agents/.
• Keep runtime sessions, conversations, and private state out of both; APX stores those under ~/.apx/.

That gives APC a durable portable layer and gives APX a clean daily-use runtime layer.

AGENTS.md stays readable by humans and broadly compatible tools. .apc/agents stays available for richer APC-native structure. APX can then bridge both without turning either one into the wrong kind of storage.

Portable projects usually fail from overloading the first file everybody touches. APC gets farther by keeping the index small and the detail where structure belongs.