What should survive when you change AI tools

I want to be able to begin work in one AI client, close it, and recover the decisions and next action in a fresh session elsewhere. I call that a cold handoff: the receiving session has the project records but none of the preceding conversation.

A failed handoff gives me a recovery problem to investigate: perhaps a decision was never saved, the new session read the wrong project, or its client did not discover the relevant file.

I draw the portability boundary around five assets: project state, reusable methods, authority rules, coordination and evidence. By open agent infrastructure, I mean shared formats, software and tests that let people inspect and maintain those assets across clients. The person or organization governing the work should be able to decide how to carry it forward.

The maintenance is part of that choice. A directory you can copy is useful. So is knowing who will repair its client-specific integration when a client changes, which test will expose the break, and how that work will be supported.

Leave room for native clients to differ

A common interface can make several models convenient to use. It can also become another dependency if its private conventions are the only place where methods, permissions or project state can be understood. I would assess its export and recovery behavior with the same care as any native client's.

Native clients should have room to develop different ways of executing and supervising work. That competition is healthy, and an open layer should help people use each client's strengths without surrendering ownership of their work.

Documentation checked September 27, 2026: The product examples below reflect documentation available on that date.

  • OpenAI documents skills that Codex can select explicitly or by matching a task to a description. Its hook documentation describes event-specific behavior and requires review and trust for an exact non-managed hook definition; changed definitions need renewed trust.
  • Claude Code's documentation describes project instructions, automatic memory, reusable skills and hooks. Those are useful native facilities with their own discovery and execution rules.
  • The Hermes Agent project documents multiple model providers, agent-curated memory, skills, a messaging gateway and subagents.

A portability design can use each client's facilities while keeping the intended methods and the tests of their outcomes available for inspection.

Keep project records usable without the first conversation

A long-running project needs a current statement of phase and status, stable reference facts, chronological history, a controlling plan, decisions, repository identity and exact next actions. A transcript can help explain how a decision emerged. A receiving session also needs to find the decision that governs the work now.

I described one set of file conventions in AI-native project management. The portability requirement is broader than those filenames: the user should be able to inspect, version, compare and open the records without the original client.

Native memory can coexist with those records. Claude Code, for example, documents automatic memory across sessions. That may help its next session, while a project-owned decision record gives another client a source it can read. Useful native memory becomes a problem for portability when a necessary decision exists only there and the receiving tool cannot recover it.

For a cold-handoff check, ask the receiving session to identify the active decision, its source, the next authorized action and any unresolved prerequisite. Compare that answer with the records. Finding the correct folder is a prerequisite; repeating the right project name is not enough to demonstrate recovery.

Carry the method and check its selection

People develop procedures for planning changes, verifying claims, reviewing code, preserving a writing voice and maintaining context. A reusable package can carry the instructions, reference material and scripts that make one of those methods useful.

The Agent Skills specification defines a package built around SKILL.md. A native adapter is the code or configuration that connects that shared method to one client's supported discovery, activation, tool and lifecycle mechanisms. The shared method can stay intelligible while its adapter takes advantage of the receiving client's features.

One canonical source lets maintainers improve the shared method once and compare installed consumers against it. An old installed copy, a failed regeneration or an adapter written for an earlier contract can leave the source and the running workflow different. Version and installation checks have to accompany the source.

Selection needs its own check. The current Codex documentation describes loading a skill's name and description before its full instructions; a task may select it implicitly. A skill that is present on disk has not thereby been selected, and a selected skill has not thereby produced good work. Retain evidence of selection where the client exposes it, then grade the resulting work against the method's actual requirements.

The skill package also does not settle the receiving environment's authority. The specification marks its allowed-tools field experimental and says support varies by implementation. A portable instruction to use a tool cannot establish that this account has permission to use it for this action.

Preserve the governing rule and establish local authority

A rule such as “production publication requires approval of the reviewed artifact” should remain legible when the client changes. The receiving environment still needs legitimate credentials, the right account or session identity, applicable permissions, trusted configuration and any action-specific approval.

Some of that work belongs in native sandboxing, permission prompts, managed configuration or hook trust. The portable layer can state the intent and record the evidence that a particular client enforces it. Copying the policy text cannot supply that evidence.

Hooks need especially precise treatment. OpenAI's current documentation identifies tool paths that its hooks cover and exceptions, including hosted tools outside the local function-tool path. It also says MCP hook errors and unavailable tools do not block the operation. Claude Code's hook reference likewise defines blocking and error behavior by event and hook type. A policy that requires stopping on a checker failure needs an implementation and test for that failure path.

I would record an unsupported mechanism as UNSUPPORTED for the named surface, and an untested one as UNKNOWN. Neither establishes an enforcement guarantee. The receiving check should observe what happens to the protected action under allowed, denied and checker-failure conditions, using an authorized disposable target.

Coordinate writers that share mutable state

A durable handoff addresses work across time. Concurrent writers add a different requirement when they can modify the same files, project record or external service.

For those shared resources, I want an explicit ownership arrangement:

  • claim the relevant files or source areas before writing;
  • use isolated worktrees and branches where the work is in Git;
  • give canonical project context a designated owner;
  • maintain heartbeats and expiring leases, so a time-limited claim has an observable owner and lifetime;
  • preserve messages and handoffs in durable records; and
  • stop conflicting work when required exclusive ownership cannot be established.

The requirement depends on the shared resource. A project without concurrent mutation does not need a distributed lease merely to read its notes. Git synchronization alone cannot choose a writer: two sessions can both pull a clean branch before making incompatible decisions. Worktrees isolate source changes but do not isolate a shared database or deployment target.

A receiving runtime needs to consult the current ownership mechanism. A copied claim record may be useful history; it does not grant a new live lease. The protocol should let another implementation acquire a non-overlapping claim and leave a recoverable handoff without access to a vendor's private conversation state.

Retain evidence with its scope and lifetime

Compatibility can change after a client update. A valid manifest may no longer be read. An installed directory can outlast its enabled plugin. A hook function can pass a direct test even though a normal session never invokes it. A connector's saved configuration can remain after its authentication expires.

I keep five evidence categories separate:

  1. Source validity: the intended package and configuration meet their declared contract.
  2. Installed version and provenance: the receiving environment has the intended bytes and can identify their origin.
  3. Live delivery: the relevant native event reaches the mechanism and produces the required observable behavior.
  4. Durable continuity and coordination: a fresh session recovers the records, and shared writers follow the required ownership rules.
  5. Authenticated capability: the current account can complete the authorized operation on the intended service.

Five checks before calling an AI agent environment ready develops the full checking procedure. For a portability inventory, each category needs a result tied to the relevant version, environment, action and time. A receiving client must not inherit a passing live result merely because the source files match. UNKNOWN cannot satisfy a required check; UNSUPPORTED should identify the precise surface and requirement.

Machine-readable reports help another implementation inspect and challenge a result. Evidence also needs a validity period appropriate to what can change. A code snapshot and an authenticated session have different lifetimes.

A compatibility corpus can become valuable public infrastructure. Sanitized fixtures for stale caches, missing hooks, expired evidence records, lease conflicts, malformed manifests and unsafe cleanup targets give vendors and runtime authors cases to reproduce before users meet those failures in real work. Each fixture must expose the failure and preserve a sound case that should succeed. Passing it establishes the conditions that fixture actually exercises.

Work through one portability inventory

In this constructed example, a team is changing AI clients while preparing release notes. Its policy permits drafting but requires designated approval of the exact artifact before publication.

AssetDurable recordClient-specific dependencyReceiving checkResponsible maintainer
Project stateRelease decision, current plan, repository identity, unresolved questions and next actionProject selection and instruction discoveryA fresh session cites the governing decision and identifies drafting as the next authorized action.Project owner
MethodRelease-note skill, references and output rubricSkill discovery, selection and available toolsInspect selection evidence when available; grade a produced draft for required entries and source fidelity. Record unknown selection honestly.Method author and adapter maintainer
AuthorityPublication rule, designated approver and artifact-specific approval requirementsAccount permissions, trusted hooks and native approval mechanismOn an authorized disposable target, check an allowed draft, a denied unapproved publication and a checker failure.Policy owner and client administrator
CoordinationOwnership protocol, durable handoff and claim historyCurrent ownership service for shared stateTry a controlled conflicting claim; verify the required conflict rejection and safe expiry behavior.Coordination maintainer
EvidenceVersioned results, inputs, observations and their validity limitsReceiving client version, environment and authenticated accountRerun required receiving checks; mark missing or stale results unresolved rather than inheriting a pass.Verifier and relevant adapter maintainer

Suppose every copied file has the expected hash, but the receiving client has no approval for the release-note artifact. Under the declared policy, the team can continue drafting if its drafting permissions are established. Publication stays on hold. The copied rule tells the client what approval is required; it does not create that approval. The policy owner must resolve the missing authorization through the legitimate mechanism.

Suppose a new client version expects a different blocking-response format, while the adapter still emits the old one. The shared skill and policy can remain correct. Even a log saying that the hook requested a block leaves the decisive question open: did the protected action stop? The adapter maintainer must update the response handling and rerun the allowed, denied and checker-failure cases against that client version.

Give contributors ownership they can sustain

That adapter repair needs someone who understands the receiving contract and can maintain its tests. Open source visibility alone does not assign that responsibility.

A project can offer bounded contribution areas: documentation and examples; skill methodology; scripts and safety fixtures; runtime adapters; onboarding and accessibility; translations and locale review; compatibility cases; and research and evidence. These roles let contributors improve the part they understand without becoming responsible for every runtime.

For each supported adapter, I want a named maintainer or team, an inspectable set of checks and a way to report a failing case. Shared specifications should use written decisions, reproducible fixtures and public migration notes. A new contributor should be able to understand why a contract changed without obtaining a private explanation from the founder.

Credit should include the person who found the failure or supplied the design insight, as well as the person who wrote the patch. A contributor who demonstrates that publication can proceed despite a block request supplies evidence the repair depends on.

Pay for maintenance without charging for a way out

My position is that the core formats, baseline safety rules, reference implementations and conformance suite should remain open. The suite checks whether an implementation meets the shared requirements. Users and maintainers need access to the parts that let them inspect, test and move their work.

Services can support that commons: organizational onboarding, migration assessments, training, managed compatibility testing, enterprise connectors, governance packages, and sponsored adapter or accessibility work. In the illustrative migration, maintaining the adapter and running checks against a new client release are concrete services with owners and costs.

Project portability and baseline safety should not become paid escape hatches. Commercial support can make the shared layer easier to adopt and maintain while leaving the formats, reference code and baseline tests available to someone who chooses a different provider.

Test use beyond the founding environment

I would judge the shared layer by whether a new user can complete a clean-room installation, an independent runtime can recover a handoff, and another maintainer can add a useful fixture. A vendor should be able to reproduce a reported failure without receiving private project data. A writer or product manager should be able to complete useful work without first becoming a plugin engineer.

Public work earns credibility when others can use it, challenge it and improve it.

For a project you intend to move, fill the five rows with its actual records, receiving dependencies, checks and owners. Choose an action whose failure would matter and identify the evidence needed before resuming it. Put the adapter's maintenance and testing costs beside the migration work so you can judge whether the promise will survive the next client change.

The opportunity is an open layer that makes every capable client more useful while keeping ownership of the work with the person doing it.