Copy a Vault Agent When the Project Needs to Own the Contract

Reusable agent templates are useful until a project needs to make one of them part of its reviewed contract. At that point, link less and copy more.

APC is the portable context layer: project-owned agent definitions live in .apc/agents/, alongside the instructions and skills a team can inspect in its repository. APX is the runtime and tooling layer: it offers a machine-wide agent vault, imports templates, builds prompts, and runs the selected agent.

Those layers support two intentionally different choices.

A vault template is a reusable starting point

APX keeps reusable agent templates outside any one project. Bundled templates ship with APX; user templates live under ~/.apx/agents/. They are convenient for a personal set of specialists: perhaps a reviewer, an ops helper, or a documentation agent used across several projects.

An ordinary import can link that template into a project:

apx agent import reviewer

That is a good fit when the template remains personal or machine-local. Updating the vault template updates what APX reads for that imported agent. The project gains a known specialist without having to duplicate a file.

But this convenience has a cost: the effective behavior is no longer fully visible in the project checkout. A teammate can see that reviewer exists, yet the definition may live only in one developer's APX home. Another machine can have a different override for the same vault slug.

Copy when behavior needs project review

If an agent's role, tools, skills, or instructions matter to a particular repository, make the repository own it:

apx agent import reviewer --copy

APX writes the Markdown definition to .apc/agents/reviewer.md. Now the agent can travel with the project. Changes appear in Git diffs. A pull request can review a newly granted tool, a changed skill list, or a sharper instruction before it changes daily work. Compatible tools have the same project-local definition to read.

A copied agent is not merely a backup. It changes the ownership boundary. The vault remains a source of reusable ideas; the APC file becomes the project contract.

For example, a general vault reviewer might have broad engineering guidance. A payments repository may need an additional instruction to verify webhook signatures and an explicit security-review skill. Linking the generic template keeps that important local difference in a user-level store. Copying it puts the difference beside the code and tests it affects.

Do not copy every template by reflex

Copying has a tradeoff: later vault improvements do not automatically flow into the project file. That is desirable for a contract, but wasteful for a casual personal helper.

Use a link when the agent is a personal reusable default and project-specific drift is not important. Use --copy when its behavior needs team review, repository history, or reproducible setup.

The distinction keeps both layers honest. APX can make agents easy to reuse. APC can make the agents a project relies on easy to audit.