Stop your team from rebuilding the same AI skills: a shared catalog that maintains itself

If your team has started using skills for AI coding agents, you've probably hit this already: someone uses an existing skill or builds one to run the test suite a certain way. Two weeks later, someone else does it their own way for the same job — different steps, different conventions, a different result — because they had no idea the first one existed. Now the agent does the "same" task one way on your machine and another way on theirs.

That's the part that actually hurts. It isn't just the wasted hour rebuilding something that already existed (though that adds up). It's that the team quietly drifts into a dozen slightly different ways of solving the same problem — inconsistent results, no shared standard, and no single place to fix anything when it breaks. Multiply it across a few people and a few months, and "skills" stops being leverage and starts being entropy.

I ran into exactly this. The fix wasn't more discipline — it was a shared catalog that's so easy to contribute to that nobody has an excuse not to — and the whole team reaches for one skill instead of each rolling their own. The trick that made it stick: a skill whose only job is to add other skills to the catalog. This post is how that works, and how to build your own.

The idea: one catalog, one source of truth

The catalog is a single repo. Skills live under skills/<category>/, where the categories are deliberately boring:

• engineering — development, testing, code review, automation
• productivity — organization, writing, planning, day-to-day workflows
• misc — everything else

At the root there's a master table — one row per skill, with its category and a link back to the source it came from. That table is the single source of truth for what the team has. New teammate? Point them at the table. Wondering if a skill already exists? Check the table before you build.

And here's the payoff that's easy to miss: when everyone reaches for the same skill, the catalog becomes a feedback loop. Someone hits a rough edge — a flaky step, a missing case, a prompt the agent keeps misreading — and they fix it in that one canonical skill. The fix lands for the whole team at once. Troubleshooting stops being something each person quietly redoes in private and starts accumulating: a shared skill gets sharper every time anyone uses it. Twelve private copies just stay broken in twelve different ways.

It's a nice idea. It also rots the instant adding a skill becomes a chore.

The catch: cataloging by hand is exactly the friction that kills it

Look at what "just add it to the catalog" actually means by hand:

1. Pick the right category and copy the folder into skills/<category>/.
2. Write an entry in that category's README — in the right alphabetical spot.
3. Resolve a permalink back to the source: the upstream repo URL, the org/repo, and the exact commit hash.
4. Regenerate the master table at the root, re-sorted alphabetically, without breaking the existing rows.

Nobody wants to do that after every skill. So they don't — and the catalog drifts out of date until it's useless. The friction is the failure mode.

The fix: a skill that catalogs skills

So I made the bookkeeping itself a skill: catalog-a-skill. You point it at a skill folder and it does all four steps. Here's the abridged SKILL.md:

---
name: catalog-a-skill
description: "Catalogs an existing skill into this repo's category structure. Use when a skill folder with a valid SKILL.md already exists and needs to be added to the catalog."
---

# Catalog a Skill

## Workflow

### 1. Read the skill
- Read `<skill-dir>/SKILL.md` and extract `name` and `description`.
- Gate check 1 — missing frontmatter.
- Gate check 2 — folder name ≠ frontmatter `name`.

### 2. Choose the category
Pick engineering / productivity / misc from the description.

### 3. Position the skill
- Copy to `skills/<category>/<skill-name>/`.
- Resolve the upstream reference from the SOURCE repo:
  commit hash (`git rev-parse HEAD`), remote URL, and `org/repo`.

### 4. Update the category README
Insert a section at its alphabetical position.

### 5. Regenerate the master table
One row per skill, sorted by name, with a permalink to the source commit.

### 6. Verify
Run `npx skills list` and confirm the skill appears.

The whole point: the contributor does the fun part (writing a useful skill) and hands the tedious, rule-bound part to the agent. That's the kind of work agents are genuinely good at — deterministic, fiddly, easy to get subtly wrong by hand.

The part that makes it trustworthy: it refuses to do the wrong thing

A naive version would happily corrupt the catalog. The real value is in the gates — the cases where it stops instead of cataloging:

• Missing frontmatter. If name or description is absent, it copies the skill into misc but does not touch the README or the master table. Then it tells you exactly which field is missing. A broken skill never silently pollutes the source of truth.
• Name divergence. If the folder is named foo but the frontmatter says name: bar, that's a red flag — it copies under the original folder name, refuses to catalog, and reports the mismatch.

That "refuse and report" behavior is what turns a convenient script into something a team can trust to run on its catalog.

How to build your own

You don't need my repo — you need the pattern. To replicate it:

1. Make the catalog repo. skills/<category>/ directories, a root README with a master table, one README per category. Keep the categories few and obvious.
2. Decide your source of truth. I use the root table; the rule is "if it's not in the table, it doesn't exist." Pick yours and make it explicit.
3. Write the meta-skill. Encode the four steps above as a SKILL.md. The non-obvious work is the bookkeeping rules: alphabetical insertion, permalink resolution from the source repo's git remote and commit, and consistent table regeneration.
4. Add the gates. Decide what "invalid" means for you (missing fields, name mismatch, wrong structure) and make the skill refuse and report instead of pushing bad entries.
5. Lower the barrier to zero. The whole bet is that a catalog survives only when contributing costs nothing. The meta-skill is what buys that.

That's it. The catalog stays current because keeping it current is now a single command, not a chore — and the team stops rebuilding skills it already has.

The full working version, gate cases and all, is here: github.com/edpittol/skills. Take it apart, adapt the categories and rules to your team, and let your agent keep the books.