A few months ago, our team built a tool to find copies of the same skill across harnesses like Claude Code, Codex and Cursor, and flag the copies that had drifted apart for review and consolidation.
Those copies existed because of how we used to share skills across our company – which is similar to how most teams share them:
- Someone writes a skill and shares it in Slack so the rest of the company can use it. Each person copies it into the tools they use and ends up with one copy per harness, since each one reads skills from its own folder.
- Later, they update the skill in Claude Code and share the new version in Slack, but their own copy in Codex never gets the update.
- Meanwhile, a teammate is still on last month’s version because they never downloaded the new one.
- Nobody notices the copies have drifted apart, because they all have the same name.
When skills diverge, people and agents end up following different instructions and getting different results. We needed everyone across the company to have the same set of skills across all their harnesses, and to stay in sync whenever a skill is added, updated, or removed.
What we heard from other teams
We spoke with a number of teams that already use skills at work to understand how they handle the lifecycle of their AI artifacts across their organisation.
The discussions centered on a few topics:
- Consistency: Which artifacts do we have, and which version is each person and agent running?
- Upgrades: When someone improves an artifact, how does everyone get the new version, in every tool they use?
- Deprecation: When an artifact isn’t needed anymore, how do we retire it everywhere?
Nobody we spoke with had a complete answer to any of the three, for their people or for their agents.
Many teams had built something close to a registry without calling it one – a central place to see which skills/AI artifacts exist across the org. However, that solves discovery, rather than consistency or lifecycle.
For example, it’s now common for teams to keep their skills in a Git repo. However, to roll out a change (e.g., a new skill, an upgrade, or retiring one that’s no longer needed), they post in Slack/Teams and rely on each person to pull it and apply it to every harness they use.
These problems aren’t new. Getting the right version to everyone and pulling a bad release is distribution, and ensuring tools can read skills the same way is interoperability. Before trying to solve distribution and interoperability for AI artifacts, we first looked for inspiration from two projects that solved a version of each: npm for code, and Apache Iceberg for data.
Lessons from npm
Before package registries like npm, developers copied JavaScript files into each project, often into a vendor folder, and passed updates around by hand. Nobody could easily tell which version a project was running, and fixing one copy didn’t fix the others.
npm made sharing code easy and predictable. You publish a version once, every install of that version gets the same bytes, and a lockfile records exactly what each project installed. Any developer can tell you which version of a library their service runs.
AI artifacts today are where JavaScript was before npm. For example, someone building an agent can’t immediately tell you which version of a code review skill their agents ran yesterday, unless they dig through their traces.
The lesson to take from npm is that distribution has to be easy. Publishing a version is one command, and so is installing it, so a fix reaches everyone who wants it without anyone copying files around. We want the same overall experience for AI artifacts.
Lessons from Iceberg
Data had open file formats for years before it had safe multi-engine interoperability. Many engines could read file formats like Parquet and ORC, but a table was just a directory of these files, with no versions and no safe way for two engines to write to it at once. In addition, each data warehouse had its own formats and metadata for tables, like snapshots and versions, so companies had to copy data between systems to use more than one engine.
Iceberg defined that layer as an open spec. Its table spec describes a table’s layout in storage, as well as its metadata. The Iceberg REST catalog spec gives every engine a standard interface to find the current version of a table, and lets multiple engines safely read and write to it. Engines like Spark, DuckDB, and Snowflake can now work on one copy of the data, on storage the company owns.
Skills today are where data was before Iceberg. Claude Code and Codex read skills from different folders, so a team that uses both keeps two copies of every skill. There’s no single copy that every harness reads from, the way Spark, DuckDB and Snowflake can all work on one Iceberg table. Prukalpa walked through the data side of this in her Context Conference keynote, Context Needs Its Iceberg Moment.
Artifact formats like Agent Skills and AGENTS.md are already open and registries exist, including ones from AWS and Google Cloud, but there’s no standard file format for a registry yet, so everyone implements their own differently, and every registry vendor does versions and metadata its own way. As a result, clients need to build a connector for every registry, and an artifact’s metadata can’t move from one registry to another.
The lesson from Iceberg is that interoperability across clients comes from a shared spec. AI artifacts need the same: one spec that Claude Code, Codex, Cursor and other clients all read to find a skill, see which version is current, and check whether it’s been retired. That spec also has to be open enough that those clients agree to read it – one vendor’s registry, even open-sourced, is one more island.
npm solved distribution and Iceberg solved interoperability. A registry for AI artifacts needs both | Source: Context and Chaos
What a registry for AI needs
npm and Iceberg made distribution and interoperability simple in their own worlds. A registry for AI artifacts needs both, and also needs to solve for a couple of issues specific to AI artifacts:
- Diligently retire skills: Code that nothing calls does nothing, but a model picks a skill from its name and description, so a stale skill that’s still installed can still be called. npm’s deprecation only warns on new installs, but for skills, we have to make sure old skills are retired across harnesses, so no person or agent keeps following instructions the team has already replaced.
- Pin versions for every agent: Cloud coding agents start in a fresh sandbox each time. If a skill lives in the same repo as the code, Git already tracks which version ran. However, shared skills often live somewhere else and an agent gets whatever version is current when it starts, so you can’t keep a team on an older version, stop a bad update halfway through, or check which version reviewed a pull request. For skills, every agent has to install a pinned version and record which one it got, so you can control what each agent runs and trace any result back to the exact skill behind it.
Even with all of this, keep in mind that a registry can’t solve every issue. For example, the same skill can behave differently in two harnesses, or with two different models. A pinned version tells you exactly which skill ran, but testing how it behaves in every tool it reaches is a different issue altogether.
Where we are today
Last month, we open-sourced our first version of ai-registry – an open spec for building a registry on storage you already own, like a Git repo. It currently includes a file spec for registries and a CLI that publishes artifacts and syncs them across tools like Claude Code and Codex.
If you run a registry to support your company, are building your own software factory, or build a harness, we’d love to hear how you’re handling distribution and interoperability, and to work on it together.
On the Context Conference panel just before my session, Prajakta Damle from Google put it in three words: open ecosystems win. The data world spent years dealing with lock-in and migrations from proprietary formats before building standards for interoperability. With AI artifacts, we’re close to day zero, so our goal is to build standards early and avoid the problems data had.
The longer version is in my Context Conference session. The spec is on GitHub, and issues and pull requests are welcome.
The Cats of Context & Chaos
Their agents are still on v1. | Source: Context and Chaos
About Context & Chaos
Context & Chaos isn’t just a newsletter. It’s shared community space where practitioners, builders, and thinkers come together to share stories, lessons, and ideas about what truly matters in the world of data and AI: context engineering, governance, architecture, discovery, and the human side of doing meaningful work.
Our goal is simple, to create a space that cuts through the noise and celebrates the people behind the amazing things that are happening in the data & AI domain.
Whether you’re solving messy problems, experimenting with AI, or figuring out how to make data more human, Context & Chaos is your place to learn, reflect, and connect.
Got something on your mind? We’d love to hear from you.
Share this article