One Owner and One Version per Skill and Agent

In an illustrative composite, a platform team keeps a skill called deploy-checklist that tells agents how to stage a release. Eight repos each carry a copy, because each team copied it the week it became useful. In March a reviewer notices the checklist skips the database migration check and fixes it in one repo. Nothing connects the other seven. Two months later a builder agent in another repo follows its stale copy, merges a migration without the check, and staging breaks on a Friday afternoon. The incident review cannot answer three questions: which copy did the agent read, who was supposed to fix the others, and which of the eight is current. Three copies differ from each other, and one differs by a single deleted line nobody remembers deleting. The repair took ten minutes. Finding out what had gone wrong took two days of diffing. Decide now: if someone asked for the owner and the running version of every skill and agent your line uses, where would you look, and would the answer exist?

This lesson gives you factory/registry.md - every skill and agent role with owner, version, status, lifecycle and the distinct-version count. It serves the Wrap stage of the loop (Slice, Gate, Run, Wrap, Prove): the layer that sits around a line that already merges and releases safely, and says who answers for each part of it.

What is actually going on

A skill is a directory with a SKILL.md file: a small header (a name that must match the directory, and a description that says what the skill does and when to use it), a Markdown body, and optional scripts and reference files. The open format is now hosted by the Linux Foundation's Agentic AI Foundation, announced alongside three other projects (Linux Foundation press release, observed 2026-10-28). The header has a free-form metadata map, which is the natural place to write an owner and a version. As far as the published field table shows, the spec itself requires neither, and it has nothing about certification (Agent Skills specification, observed 2026-10-28). Ownership and approval live outside the format. That gap is what this lesson fills.

Copies multiply because copying is the cheapest way to distribute a skill. Anthropic's own team reports a catalog of hundreds of internal skills that sort into nine categories, and it warns that a skill straddling several categories confuses the agent (Anthropic, self-reported, observed 2026-10-28). Once skills are that numerous and spread across repos, no human holds the list in their head. The registry is the list written down.

Three ideas make it work. First, discovery over registration: nobody fills in a form. An ingest job reads skill files from the conventional paths in each repo and builds the entries, so merging to the default branch is the registration. Backstage describes this shape for AI assets, with entity providers that generate entries from skill and rule files and point each back to its source file (Backstage docs, observed 2026-10-28). An AWS-authored open-source registry ingests skills from code hosts and scans them when they are registered (AWS Open Source Blog, observed 2026-10-28). Second, the distinct-version count: hash each copy of a skill, count the different hashes, and you get a drift number you can read in one second. Third, separate control loops: an agent is a service account and a skill is a library, and each changes through its own door.

The diagram shows the path a skill takes from a repo to an agent, and the drift signal that comes back from the registry to the owner.

Read it left to right and notice what is missing: no arrow lets an agent pull a skill that skipped the registry. The dotted edge is the cheapest alarm in the lesson, because a number above one means two people believe they are running the same skill and are not.

The rule and its condition

A skill nobody owns is not shared knowledge, it is a rumor with a filename. Use a registry with ingest, owners and a lifecycle when more than one repo or agent consumes the same skill; otherwise git history already is the registry, so skip the machinery and say so. Register by discovery whenever skills are files in repos you control. Count distinct versions on every ingest, and treat any skill above one as an open issue for its owner.

Give agents and skills separate change control. A skill edit is a library change: a pull request, the skill owner's approval, a version bump, and certification before agents may pin it. An agent change is a service-account change: who operates it, what it may touch, which skills it pins. A skill can quietly widen an agent: the format's optional allowed-tools field pre-approves tools while a skill is active, and the spec marks it experimental (Agent Skills specification, observed 2026-10-28). A diff that adds a tool there changes what an agent may do, so route it to the operator too.

Only the second row follows the Backstage and AWS documents above; the rest is the lesson's own framing, not a sourced claim.

The lifecycle has three outcomes, and the registry records all three. Certify: the entry has a name, an owner, a version and one category, and a reviewer judges that the description says what the skill does and when to use it. Deprecate: the owner sets a remove-by date, and every agent that pins the skill is flagged the same day. Reject: the entry stays listed with its reason so the same text is not resubmitted. Certification is a convention you define. One vendor describes a certification gate in which a regression in a skill demotes the agents that use it, but no independent source tests that rule, so treat the thresholds as yours to set.

Worked case

Illustrative composite. A five-agent factory serves four repos. The agents are a spec writer, a builder, a reviewer, a release shipper and a triage agent. Each repo keeps skills under its own folder. A first ingest finds six distinct skill names spread across nineteen copies; the figures below come from that scan and are modeled, not measured at a real company.

Three options are on the table.

Option A: a shared spreadsheet where every team lists its skills. Cheap, and done by Friday.

Option B: one central skills repo that every other repo copies from on a schedule. One source of truth on paper.

Option C: ingest the skill files from the four repos into a registry file with an owner, version, status, lifecycle and a distinct-version count, and pin every agent role to a version.

Decide now: which option, and what is the first thing that goes wrong with each of the others?

Option A fails first. A spreadsheet is a second step, so it is correct on the day it is filled and wrong a month later; it also cannot see a copy somebody edited, because it lists names rather than contents. Option B fails quietly. The sync overwrites some copies and not others, a consumer edits its copy to get unblocked, and nobody counts the result, so the single source of truth sits beside three silent forks. Option B is a fine distribution mechanism. It is not a registry, because it produces no count and assigns no owner.

Option C is what you build. The ingest job gives the file its facts, hashing every copy and filling the copies and distinct columns. Humans own only the judgment columns: owner, status, lifecycle. The scan in this case finds ten distinct versions for six names, so the drift is four, and three skills carry most of it. The numbers matter less than the habit: the file now answers the opening question with a lookup, not an investigation.

Two small scripts keep the file honest. The first hashes every copy of every skill directory and prints any skill with more than one distinct hash; it is the source of the distinct column. The second reads the table, flags a missing owner or version, and recomputes the totals.

# drift.sh: run from a folder holding repos/<repo>/skills/<skill>/for name in $(ls -d repos/*/skills/* | xargs -n1 basename | sort -u); do  n=$(for d in repos/*/skills/"$name"; do        (cd "$d" && find . -type f | sort | xargs sha256sum | sha256sum | cut -d' ' -f1)      done | sort -u | wc -l)  echo "$name $n"done | awk '$2 > 1'

# audit.sh: reads the Skills table of factory/registry.mdawk -F'|' '  /^## / { in_skills = ($0 ~ /^## Skills/); next }  in_skills && /^\| [a-z]/ && !/^\| skill / {    n++; d += $9    if ($4 ~ /^ *$/ || $5 ~ /^ *$/) print "NO OWNER OR VERSION:" $2    if ($9 + 0 > 1) print "DRIFT:" $2 "has" $9 "versions"  }  END { print "names=" n, "distinct=" d, "drift=" d - n }' factory/registry.md

Illustrative composite. I ran the drift script against a three-repo sandbox with one deliberately edited skill, and the audit script against this registry block. The audit printed the three drifting skills and the totals line names=6 distinct=10 drift=4; the drift script flagged the one skill whose copies differed. Adjust the glob in the first script to your real folders. Common conventions include a .claude/skills or .agents/skills folder inside each repo.

The pins column is the second half of the work. The reviewer is restricted because one of its skills is still pending, and the triage agent is flagged because its only skill is deprecated. In both cases the rule in the file, not a person's memory, decides what the agent may do next. The cost of Option A is a list nobody trusts. The cost of Option B is forks you cannot see. The cost of Option C is an ingest job and a weekly look at one number.

Faded case

Skip to the open case if this is familiar. The shape is the same as the worked case, with the work done by hand on a smaller scene so you can feel what the script does for you. A scan has already run and produced one short hash code per copy, which is all the registry needs to see. Your job is the arithmetic, and then the one decision that arithmetic cannot make. Treat a copy that is absent differently from a copy that differs: the first is a gap, the second is a fork. Both matter to an agent that pins the skill, but only the second moves the drift number. Work it on paper before you open the answer, because the habit you are building is reading the count and the cause together.

Illustrative composite. Three repos each hold some of four skills. The short codes are the first four characters of each copy's directory hash.

Compute the three numbers the registry needs: names, distinct versions and drift. Then make the one decision the script cannot make for you: for run-tests, two repos hold 41ab and one holds 77e1. Which version does the registry record as current? Write down who you would ask and what you would do with the repo that holds the other version. Also note what the table shows for release-notes: one repo has no copy at all. Decide whether that absence counts toward drift, and what a missing copy means for an agent in that repo that pins the skill.

Open case

Your factory has four repos and three agents. A scan finds one skill, review-checklist, in six copies with four distinct hashes. The entry's owner field is empty because the engineer who wrote it left last quarter. The reviewer agent pins the skill. A fix for a missed-injection check landed in only one of the copies. Nobody has decided which copy is current. Two agents in other repos have started citing the skill's old wording in their review comments, and the next scheduled release is on Thursday. You have no authority to rewrite the skill yourself and no time to convene a committee. Write the first three actions you would take today, in order, and name one tempting shortcut you would refuse. The quiz grades what you do first and what you do not do.

Where this breaks

No source measured an outcome. Everything above comes from standards, product documentation and engineering posts describing a mechanism. The Agent Skills format, the Backstage catalog kind, and the AWS registry are well specified. No source we read reports fewer incidents, faster merges or lower cost from running a registry. Treat the design as how teams are told to build it, and measure your own distinct-version count before and after.

Registries decay in a different place. Ingest keeps the list complete, but ownership still rots when an owner leaves, as in the open case. The Backstage example for the skill kind uses a v1alpha1 version, and neither it nor the AWS registry names a production adopter in the pages we read. One catalog vendor's write-up claims hand-filled registration decays and shadow agents surface during incidents; that is a vendor claim, unmeasured. The AWS design routes everything through a single gateway; that is a single point of failure by our inference, not by their claim.

The count sees bytes, not meaning. A trailing space makes two copies look different. Two identical files can behave differently under a different model. The count is a smoke alarm, not an audit. The skill specification repository has been quiet for a while; read that as a stable spec, not abandonment.

Neighbours. In Agent Fleets, lesson 5, you chose a containment tier per agent; this file records which skills each of those agents carries. Agent Fleets, lesson 7, keeps credentials out of the agent's hands; this lesson asks who answers for what the agent reads. The same drift appears in Loop Engineering, lecture 7, where an upgrade ledger tracks template versions across instances, and Harness Engineering, lecture 16, treats rules, commands and reusable prompts as files worth versioning.

Key Takeaways

• Count distinct versions of every skill on every ingest; any number above one is a ticket.
• Register by discovery: merging the skill file to the default branch should be the registration.
• Name one owner per skill and one operator per agent before either gets write access.
• Route allowed-tools changes to the operator, because a skill edit can widen an agent.
• Treat registry design as standards and docs, not proven results, and measure your own drift.
• A skill nobody owns is not shared knowledge, it is a rumor with a filename.

What You Have Now

factory/registry.md - every skill and agent role with owner, version, status, lifecycle and the distinct-version count. It sits in the factory/ directory next to the protected-paths and risk-lanes files, and it should itself be a protected path so an agent cannot edit the list that governs it. It serves the Wrap stage: from here on, any gate that asks whether an agent may act can look up its skills, their status and their owner in one place. The next lesson attaches an identity and a named human to each agent role you just listed.

Further Reading

• Agent Skills specification - the exact fields a skill carries and what the format leaves to you.
• Backstage: AI in the catalog - how skills, rules and MCP servers become catalog entities with owners and lifecycle.
• AWS Open Source Blog: governing AI assets with an MCP gateway and registry - registry, access control and a scan at registration, in one design.
• Anthropic: lessons from building Claude Code, how we use skills - a first-party account of skill categories at scale.
• AGENTS.md - the repo-level instruction file format that a catalog can check for.

Exercises

1. Count your own copies. Pick one skill your agents use and run the drift script across every repo that holds it. Record the copies, the distinct count and the owner, even if the owner is "nobody".
2. Write the first five rows. Create the Skills table of factory/registry.md for the five skills your agents rely on most. Mark each owner, version, status and one category. Run the audit script and fix every flag.
3. Add the agent half. List every agent role, its operator and its pinned skills, then write the tripwire: what happens to an agent when a pinned skill is deprecated or still above one version after two weeks. Have someone other than the author read it and say who would be paged.

Check your understanding