cankun.me
Jun 24, 2026 · 3 min read /

A Shelf for My Agent Skills

One canonical library, skills toggled on or off per coding agent, and updates that never clobber the ones I'm still writing.

A long shelf holds many dormant blank volumes while a selector lamp activates only a chosen few

Every coding agent I use keeps its skills in a different place: Claude Code reads ~/.claude/skills, Codex reads ~/.codex/skills, and Cursor has its own folder, on top of the per-project .claude directories and a few more stashed in an Obsidian vault. Before long the copies drift apart, and I end up rewriting skills I already wrote or forgetting which ones even exist.

Dumping everything into a single shared folder and pointing every agent at it is the obvious fix, but it trades one problem for a worse one. Every session then loads hundreds of skill descriptions at once, and you pay for all of them on every turn whether you use them or not.

So I built skillshelf, a package manager for agent skills that keeps one canonical library on disk and loads skills on demand rather than all at once.

One library, nothing auto-loads

The library is a plain git repo holding a single copy of each skill. Nothing in it loads automatically, so the token cost stays near zero until I actually ask for something. From the command line I can search the shelf, read any skill's instructions, and bundle skills by domain tag; a skill tagged both coding and bioinfo shows up in both bundles from that single copy on disk.

skillshelf library view: a scrollable list of skills, each with per-agent deployment toggles, a domain sidebar, and a scope switcher across the top
The library view lists every skill in one place, with per-agent toggles right in the row.

Toggle per agent, not per copy

I wanted a visual interface for the daily toggle work. Each skill has a row of switches, one for Claude, Codex, and each of my other agents, and turning one on symlinks the skill into that agent's directory. A scope switcher at the top lets me apply changes globally or just to the project I am in, so a one-off project loadout never leaks into everything else.

Rather than storing its own state, the app reads directly from the filesystem every time. The UI shows what is actually deployed on disk, so it never reports a skill as active when a symlink is broken or a stray copy has drifted. When something is out of sync, it surfaces a step to resolve the conflict instead of pretending everything is fine.

Selective updates that never clobber my own work

I could almost have lived with a folder of manual symlinks, except that I am always writing new skills and never want an update to overwrite one I am in the middle of editing.

To prevent that, skillshelf distinguishes between copied skills and linked ones. For skills I downloaded and want to pin, the library stores a real copy. For the skills I actively develop myself, I shelve a link to the skill's own git repo instead. That development repo stays canonical, my edits show up live, and update and outdated skip linked entries entirely so they never reach back into my working repo. For the copied skills, an update re-pulls only the upstream instruction body and leaves my tags and notes alone in their separate file, swapping in the new version cleanly without touching anything I added.

skillshelf detail drawer: the rendered SKILL.md body on the left, with provenance, an agent-by-scope deployment matrix, tags, and lifecycle actions on the right
The detail drawer shows the skill's body alongside its provenance, tags, and an agent-by-scope deployment matrix.

How it fits with Vercel's skills CLI

vercel-labs/skills is a good tool that solves the other half of this problem. Vercel's skills CLI is a distributor: point it at a repo or the skills.sh registry and it fetches a skill and installs it into your agents in one step, where installed means present and loading. skillshelf is for managing the skills I already have, most of them scattered across local dirs and never published anywhere. It keeps one passive shelf, separates owning a skill from loading it, and pulls skills into a project on demand by tag so no session pays to load the whole collection at once.

Because both tools speak the same SKILL.md format, they work together cleanly. I can vendor something out of Vercel's ecosystem into my library, then bundle and load it like everything else: Vercel's tool is how a skill reaches me, and skillshelf is how I keep a hundred of them organized.

Where to find it

skillshelf is a Bun CLI (skl) with a Tauri desktop app built on top of the same engine. The app reads the real library and every toggle writes the same symlinks the CLI does, so the two never disagree. It is open source.