Portable by default

The principle

Agents, profiles, and workflows should move without being rebuilt around a single vendor.

This is not an argument against using good tools, including commercial ones. It is an argument about which artifacts belong to you. A harness is infrastructure and infrastructure gets replaced. What an agent is, what it knows how to do, and what it has learned about your work are not infrastructure. They are the output of months of accumulated effort, and they should not live inside something you might change.

What cannot be recreated

The useful test for whether something needs to be portable is whether you could rebuild it from knowledge you still have.

Things that pass the test, meaning they can be rebuilt and therefore need not be portable: deployment configuration, monitoring dashboards, model choices, the harness itself. All ordinary work.

Things that fail it:

• Agent identity and permissions. Including the reasoning behind narrow grants, which is the part nobody writes down and everybody needs when a permission is questioned.
• Accumulated state. What agents learned: conventions, corrections, open threads. There is no other source for this. It exists because sessions happened.
• Skills and procedures. Organizational knowledge that took months to elicit from people who held it in their heads.
• Semantic definitions. What a metric means, which table is authoritative. Recreating these means having the same arguments again with the same people.
• Evaluation sets. Real tasks with known answers, tedious to assemble and required for judging anything.

Everything on that second list should be a file, in version control, in a format more than one thing can read. That is the whole practical content of this principle.

Lock-in happens by accumulation

Nobody decides to become dependent. It happens one reasonable decision at a time.

A team adopts a platform for model access, which is easy to leave. Then they use its tool integrations, because assembling those separately is real work. Then they define their agents in its format, because that is what the interface offers. Then they run on its hosting, because operating a process is a burden they did not want. Then their agents accumulate memory in its store, because that is where memory lives.

Each step had an immediate benefit and no visible cost. Collectively they produce a system that cannot move, and the team discovers this at the moment they want to.

Two of those five steps matter far more than the others. Agent definitions and accumulated memory are the artifacts with no other source. Model access, tool integrations, and hosting can all be rebuilt from knowledge you still have. A definition entered into a web form and a memory store with no export are what actually pin you.

Degrees of portability

Portability is not binary, and naming the levels makes the conversation more productive than arguing about whether something is portable.

The gap between the third and fourth levels is the one people underestimate, and I say that as someone who writes specifications. A published document with a single implementation has not been tested as a specification. The second implementation is what proves the document was sufficient, which is why counting independent implementations is a better signal than reading the specification.

Applied to my own work: Agent Skills and MCP sit at the fourth level. My specifications sit at the third, moving toward the fourth. That is a real distinction and I would rather state it than blur it.

Portability needs honest projection

A format alone does not deliver portability across heterogeneous systems, and this is the part I got wrong before I got it right.

Runtimes support different things. A portable artifact moved between them does not necessarily mean the same thing in both places. There are three ways to handle that and only one is safe.

Pretending uniformity and silently dropping what is unsupported is the worst. An artifact declaring a boundary runs somewhere that ignores it, and the operator believes in a control that does not exist. The system is now less safe than if the artifact had never existed, because the artifact manufactured confidence.

Refusing anything not fully supported is safe and reduces portability to the intersection of every implementation, which is close to nothing useful.

Projecting and reporting honestly is the third. Native here, approximated here, degraded in this specific way, unavailable there. The operator decides whether that is acceptable for the work.

This is why I put a requirement into the Open Agent Profile specification that implementations must publish what they do not implement. Partial support is fine. Partial support that looks complete is not, because someone will review an artifact, run it elsewhere, and get something different from what they read.

What it costs

Portability is usually argued for and rarely priced, which makes the argument weaker than it should be. The costs are real.

You work at the intersection. A portable format supports what multiple implementations support, which is less than the best of them offers. That means occasionally declining a capability that would have been useful.

Artifacts need maintenance. Skills go stale, profiles reference systems that changed, graphs point at retired tools. Portable artifacts are code-adjacent and need the same validation and review. Product state does not require this because the product enforces its own consistency.

Versions need tracking. Each specification adopted is one more thing with a version and a migration path.

The benefit is contingent. The payoff arrives if you migrate, if a vendor changes terms, if a team splits. None of those may happen, and the cost is paid regardless.

That asymmetry is why portability loses arguments in the moment. Anyone advocating for it should be able to state the costs, because an advocate who cannot is easy to dismiss.

The internal case is stronger

The vendor-migration argument is the weakest one available, and it is the one people usually lead with. The benefits that arrive immediately are more persuasive and more real.

Definitions move between teams.A metric definition inside one group's BI project cannot be used by another group's agent, so the second group defines their own, and the organization now has two answers to one question. A portable definition prevents that on day one.

Procedures survive turnover.Knowledge in one person's head is not portable. When they leave, it leaves. A skill capturing the same procedure moves to whoever needs it.

Non-engineers can review. A profile or a skill is a file a domain expert can read, correct, and approve, with confidence the correction takes effect. Product configuration is not reviewable by the people responsible for the process.

Colleagues can pick things up. An agent someone built is a file another person can copy and use, rather than a setup they have to reproduce from a description.

None of these depend on ever migrating anything. They accrue while you stay exactly where you are, which is the version of the argument I would lead with now.

Portability through time

Most discussion of portability is about moving between systems. The harder direction, and the one I think about more now, is moving forward into a future where the tools that created an artifact no longer exist.

The data layer solved this decades ago and the lesson transfers directly. A Parquet file written today is readable in fifteen years because it is self-describing: the schema travels with the data, the encodings are documented, and no external system is required to interpret it. That was designed in, and it is why the format outlived several generations of the engines that wrote it.

Agentic artifacts mostly do not have that property yet. Judged individually:

• Skills age well. Markdown with a documented frontmatter convention is readable by a person with no tooling at all, which is the strongest form of durability available.
• Profiles age well for the same reason, provided the artifact declares which specification version it targets. Without that, a future reader has to guess what a field meant.
• Graphs age well as documents and less well as executable things, since they reference tools and systems that may be gone. A graph is still readable as a record of intent, which is often what you want from it years later anyway.
• Accumulated state ages worst. It describes systems, people, and situations that change, and a fact recorded three years ago with no timestamp or provenance is worse than nothing because it is confidently stale. This is why I insisted that state entries carry confidence and source rather than being plain text.

The habits that follow are small: declare a version in every artifact, timestamp anything describing a state of the world, and prefer text formats a human could interpret without software. All three cost nothing at write time and cannot be added later.

Testing it

Portability that is never exercised quietly stops working. The tests are cheap and almost nobody runs them.

1. Load your skills in a second harness. Once. See what activates and what does not.
2. Run one profile through a broker onto a second runtime. Read the projection report, not just the outcome.
3. Export everything and try to reconstruct. The most revealing test and the one nobody runs. Could a new environment be stood up from the exports alone?
4. Check that the evaluation set is itself portable. An evaluation harness tied to one provider is a portability gap in the thing you use to measure portability.

The uncomfortable version of the question: if your primary vendor terminated your account tomorrow with a thirty-day export window, what would you actually be able to take? The answer is your real score.

Objections I take seriously

Two objections to this principle are usually dismissed and are correct in specific cases. Since I advocate for portability constantly, I would rather engage with them than pretend they do not land.

It is premature generality

The argument is that building for a switch you may never make adds indirection now for a benefit later, which is the definition of speculative design. Often true. A custom abstraction over a database you will never change is pure cost.

Where it fails is when the abstraction is nearly free. One function that every model call goes through is not an architecture, it is a habit. It costs an afternoon and converts a multi-week change into a configuration edit. The test is whether the abstraction is cheap and whether the component is genuinely likely to change. For models and harnesses right now, both are true, and they will not always be.

The intersection is worse than any specific option

The argument is that portable systems work at the lowest common denominator, giving up the best capability of every component. This is real, and I feel it every time I decline to use something because only one implementation supports it.

The resolution is not to reject the constraint but to place it deliberately. Use specific capabilities where they matter and the dependency is bounded, and keep the surrounding structure portable. Prefix caching is a good example: adopting the design rule it implies, which is stable content first, costs nothing where it is unavailable and pays where it is. Capability adopted in a way that degrades gracefully is not lock-in.

There is a third objection that is simply true and rarely stated: portability has a maintenance cost even when nothing changes. Abstractions drift from what they abstract. Evaluation sets go stale. A second path never exercised stops working. If you are not going to exercise it, be honest that you have written documentation rather than built a capability. I have shipped both and only one of them helped.

What this is not

Portable is not the same as identical. An artifact moved to a runtime with different capabilities may behave differently. The goal is that it moves and the differences are known, not that they do not exist.

Portable is not the same as standard. A format can be standardized and unportable if no second implementation exists, which is a criticism that applies to young specifications including mine.

Portable is not an argument for avoiding good tools. Use whatever works best. Keep the definitions in files you own, and the tool stays a choice rather than becoming a commitment.