A portable agent setup

Every harness has its own instruction file, its own config format and its own idea of where a skill lives. That is fine while you use one. It becomes expensive the week you switch, or the week a client asks you to work in their environment.

The fix is not a framework. It is a small set of plain files that you own, plus a thin adapter per harness. Keep the content vendor-neutral and the adapters boring.

The canonical files

agent/
|-- AGENTS.md            project instructions, tool-neutral
|-- prompts/             reusable prompts, one file each
|-- skills/              Agent Skills folders, one per skill
|-- references/          source notes, style samples, schemas
|-- checks/              commands that prove a change works
`-- .env.example         names of required variables, never values

The repository root is also fine. What matters is that the content is not trapped inside a chat history or a vendor-specific database.

Instructions

Write one project instruction file and keep it short. It should answer four questions:

1. What is this repository, and what is the one command that proves a change works?
2. What must the agent never touch: secrets, generated files, production data, vendored code?
3. What is the review path: branch, test, commit message, changelog?
4. What should the agent ask about instead of guessing?

Harnesses read different filenames. A common pattern is AGENTS.md at the root, with CLAUDE.md or another vendor file containing a one-line pointer to it. Do not duplicate the content; duplicate the pointer.

Prompts

Keep a prompt in a file when you use it more than twice. Include:

• Use when — the situation, not the topic.
• Inputs — the evidence the prompt needs.
• Output contract — the sections a good answer contains.
• Guardrails — the checks the model must run before it answers.

The prompt library is written in this shape. Copy a template into prompts/, edit it for your context, and keep the version that worked.

Skills

A skill is a folder with a SKILL.md and optional references, scripts and assets. The skill packs explain the format and give four starting points. Three rules keep a skill portable:

• Do not put a model name in the instructions. Describe the task, not the vendor.
• Do not put a credential in the folder, not even in an example.
• Do not depend on a tool the harness may not have without saying so in the description.

If a harness uses a different skills directory, symlink or copy the folder. Keep the canonical copy in agent/skills/.

Tool configuration

MCP servers, shell allowlists and model settings are the least portable part. Keep a small tools/ directory with one example config per harness, and a tools/README.md that says which harness reads which file. Do not commit tokens; use environment variables and a secret manager.

When you move, re-create the configuration from the examples rather than copying a working directory wholesale. It is slower once and cleaner afterwards.

Secrets

• Keep secrets in the environment or a secret manager, never in a prompt, a skill or a repository file.
• Give the agent the name of the variable, not the value.
• Rotate a key after any session where you cannot explain what the agent read.
• In a client repository, ask which secret store they require before you configure anything.

The migration checklist

Run this before you switch harnesses:

1. Copy AGENTS.md and confirm the new harness reads a file that points to it.
2. Copy prompts/ and skills/; check that the new harness sees the skill descriptions.
3. Re-create one MCP server and confirm the tool list the agent reports.
4. Run the checks/ command and the three tasks from the 45-minute bake-off.
5. Revoke any token that was stored in the old harness's config.
6. Update the decision log with the date and the reason.

What portability does not buy

It does not make the harnesses equivalent. Permission models, context handling and cost still differ. It does not make a prompt model-neutral in quality; a prompt tuned for one model may need a pass in another.

What it buys is a cheaper switch. The accumulated judgment — the prompts, the checks, the source notes — stays yours, and a new model becomes a swap rather than a rewrite.

Related

• Harness comparison — what changes between the tools.
• Skill packs — the folder format and four starting points.
• How to test a harness in 45 minutes — the test after the migration.