---
title: "A portable agent setup"
description: "Keep the instructions, skills, prompts and tool configuration in plain files so a harness change is a swap, not a rewrite."
canonical: "https://www.diginomads.win/harnesses/portable-agent-setup"
source: "content/pages/harnesses/portable-agent-setup.md"
updatedAt: "2026-11-10"
---

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

```text
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](/prompts) 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](/skills) 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](/harnesses/how-to-test-a-harness).
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](/harnesses) — what changes between the tools.
- [Skill packs](/skills) — the folder format and four starting points.
- [How to test a harness in 45 minutes](/harnesses/how-to-test-a-harness) — the test after the migration.

## Structured data

```json
{
  "@context": "https://schema.org",
  "@type": "WebPage",
  "name": "A portable agent setup",
  "url": "https://www.diginomads.win/harnesses/portable-agent-setup",
  "description": "Keep the instructions, skills, prompts and tool configuration in plain files so a harness change is a swap, not a rewrite.",
  "isPartOf": {
    "@type": "WebSite",
    "name": "DigiNomads",
    "url": "https://www.diginomads.win/"
  }
}
```