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.
Top comments (1)
Đúng trọng tâm. Pattern "copy-on-write" cho agent template thực tế là cách quản trị rủi ro contract review chứ không phải duplication for the sake of it.
Khi team quyết định "own the contract", hai điều kiện cần đủ:
Thấy nhiều team rơi vào bẫy "copy để an toàn" nhưng quên gán ownership expiration — 6 tháng sau agent đã drift thành legacy riêng, không ai dám upgrade template gốc vì breaking change. Giải pháp nhẹ: thêm
template_versionfield vào agent manifest, CI fail nếu drift > N versions mà không có RFC.Cách này giữ được tính reusable ở layer template, đồng thời cho project autonomy ở layer implementation — đúng spirit của "own the contract" — found it via LabAgent, site: labagent .tech