For decades a command-line tool shipped with a man page so a person could learn to drive it. Now the reader is an AI agent, and it needs the same thing in a form it can read. Here’s my take: skills are the new man pages.
I remember when the man pages also came as a book. Around 1995 — before searching the web was really a thing — somebody printed Linux Man: The Essential Man Pages for Linux, about twelve hundred pages of man pages, bound on paper. For me it didn’t replace the actual man pages - it was a discovery mechanism. I’d pour over it trying to learn how to Linux SysAdmin. Then typing “man rsync” was how you looked up the syntax for that rather obtuse command (or whatever command). Man pages literally were how one got up to speed on how command line tools worked.
But it’s almost 2027 and the old days called and want their man pages back: they are exactly the wrong shape for agents. Agents want SKILLS.
Man pages taught people. Skills teach agents. Same job, new reader.
So here’s the whole proposal in one breath: a tool should carry its own skill, and there should be one standard place to put it. Two small, boring pieces — and the order they go in is the argument.
The skill format is already converging — it’s a directory with a SKILL.md in it, and the major agents mostly agree on that. What nobody standardized is the two boring, load-bearing things around it: how a tool hands you its own skill in the first place, and where that skill then lives. Boring is exactly where the pain is. I wrote these up as two independent draft proposals — IETF-Internet-Draft style so they’re easy to pick apart, Experimental, and (this matters) either one works without the other. Let me take them in order.
Start with the tool carrying its own skill #
This is the man-page half, and it’s the part I’m most excited about. The Skill Self-Installation Specification says a conforming tool either ships its skill in the package or — better — embeds it right in the executable. In Go that’s easy with //go:embed. Then it exposes two subcommands with fixed names:
| Subcommand | Does |
|---|---|
install-skill |
Writes the carried skill into the shared store, ready for any agent. |
print-skill |
Prints the carried skill to stdout. |
The fixed names are the whole trick. Because the spec pins them, the install step is discoverable. Hand an agent a conforming binary it has never seen, and it can run <tool> print-skill, read how to drive the thing, and go — with nothing installed. The binary and its documentation ship as one artifact. Whoever has the tool has the manual, in a form the agent can actually use. That’s the man page again — except the reader is a machine, and it never has to leave the binary to find it.
But where does the tool write it? #
install-skill writes the skill somewhere. Where, exactly? That innocent little question is what turns a neat trick into a standards problem — and I learned it the hard way, not from theory. I didn’t set out to write a standard. I set out to stop being insane: doing the same annoying thing over and over.
I’ve written before that the tooling is the new model — that the workflow around the agent matters more than which brain is underneath. I built dot-agents to make my setup portable: same skills, same security rules, same workflow discipline, running across both Claude Code and Mario Zechner’s pi. One config, many agents. Great in theory.
And I run several on purpose, not just to hedge my bets. Different agents win in different places. A heavy, feature-rich agent is great driving a frontier model in the cloud — but it’s way too heavy for local inference. On a local box a lean agent with a small tool set finishes faster and burns a fraction of the tokens, because all that machinery is prefill you re-pay on every single turn. So I keep a fat agent for the cloud and a lean one for the metal, and I want the same skills available to both - or a subset of the same skills, at least.
Because there’s a subtler reason to care, too: pile too many skills in front of an agent and it gets confused. It spends context chewing through descriptions it’ll never use, and every so often it reaches for the wrong one. More is not better. Which skills an agent even sees is something you want to control — curated, not a firehose — and that control is a whole lot easier when there’s one place that holds the set than when it’s smeared across five folders you hand-edit.
Here’s the part that bit me. Making “one config, many agents” actually work meant copying the same skills into ~/.claude/skills, then into pi’s folder, then — when I started the agent bake-off — into oh-my-pi’s folder, and hax’s, and kit’s. Claude Code reads ~/.claude/skills. Copilot reads ~/.copilot/skills, etc. Each agent reads only its own proprietary directory. Everybody picked their own path and nobody coordinated.
So a skill I wanted everywhere lived in N places. Fix a bug in one skill, fan the fix out N times. Forget one, and now an agent is running the old version and you’re debugging a difference that has nothing to do with the agent. Been there. It’s dumb, and it compounds every time you add an agent or write a new skill.
So — back to the question — where should install-skill write? Into ~/.claude/skills? Then it only ever helps Claude Code, and every tool that ships a skill has to learn about every agent that will ever exist. That’s the exact mess I was already living in, just automated. I don’t want a standard that blesses one agent. We need one neutral place that belongs to no agent in particular — and then a way to get skills from there to wherever each agent actually looks.
A standard place — and a way to fan it out #
The Skills Directory Specification does the first half: it names one agent-neutral store and defines what a skill directory has to look like to sit in it. The location is the obvious one if you know Linux conventions — it’s under XDG:
${XDG_DATA_HOME:-~/.local/share}/skills/<name>/SKILL.md
One place. One directory per skill, name-unique by construction. A producer — a git clone, a .deb, or a tool’s install-skill writing out its embedded skill — writes there once. Now install-skill has an answer that doesn’t care which agents you happen to run.
The day every agent reads that store directly, we’re done. But that’s not today — today each agent still reads only its own folder. So the standard has to cover the bridge, too: taking the skills in the neutral store and symlinking (symbolic-linking) them out to wherever each specific agent expects to find them. One real directory in the store, a cheap symbolic link in ~/.claude/skills, another in ~/.copilot/skills, and so on. Every agent sees the same skill, and there’s still exactly one file to edit. (Where a symlink can’t reach — into a sandbox or a container home — you fall back to a real copy; hold that thought.)
The companion tool: sm (and ms) #
A spec nobody implements is a blog post with delusions of grandeur. So there’s a reference implementation: sm and ms (skills-mapper), two small Go binaries that do exactly the bridging I just described — and nothing more.
skills-mapper: one central burrow, tunnels to every agent.
smgoesstore to agents . Until agents read the XDG store natively,sm syncmirrors it into each agent’s proprietary folder — symlinks by default, or real copies with--copyfor sandbox and container homes a symlink can’t reach. It lists the store, links or copies into each agent, and reconciles. That’s it. It doesnot populate the store, fetch anything, or transform skills.msgoes the other direction — the on-ramp. It ingests the skills youalready have in an agent (today, a Claude Code tree, including the standard skill folders nested inside plugins) into the store, normalized to the directory spec. Runmsonce, then letsmfan everything out to the rest.
flowchart LR
existing["skills an agent<br/>already has"] -- "ms (one-time ingest)" --> store
producers["producers:<br/>git clone, .deb, embedded binary"] -- write --> store["canonical store<br/>~/.local/share/skills/<name>"]
store -- "sm sync" --> claude["~/.claude/skills"]
store -- "sm sync" --> copilot["~/.copilot/skills"]
store -- "sm sync" --> others["pi · oh-my-pi · hax · kit"]
The design discipline is the part I’m proud of. sm is deliberately dumb and neutral: it sees a directory of skills it did not create and mirrors it. The proprietary knowledge — “Claude looks here, Copilot looks there” — lives in one narrow place, the fan-out, instead of being smeared across every single tool that ships a skill. And it’s safe by provenance: sm keeps a private record of every link and copy it made, and will only ever remove or replace something it can still identify as its own. It never clobbers a skill you placed by hand.
And yes — sm and ms eat their own dog food. Both carry their own skill embedded in the binary, installable with sm install-skill or printed with sm print-skill. The tool that implements the spec also demonstrates it. That felt right.
Where this really bit me: isolated agents #
Here’s the case that turned this from “mildly annoying” into “okay, I’m writing a standard.”
I’ve been building a thing I’m calling agentdev — it runs a coding agent in an isolated container whose entire “self” (config, history, memory) lives in one swappable profile folder on the host, so you can run a genuine clean room, or a named profile, or an amnesiac-but-remembers-what-it-learned mode. It’s its own rabbit hole and I’ll be writing a whole post about it shortly, so I won’t oversell it here. But it exposed the skills problem in its sharpest form.
A clean-room agent is, by design, a brand-new user with nothing. No history, no memory — and no skills. Every one of those isolated profiles needs its skills seeded from somewhere. If my skills lived in five agent-specific folders on the host, “seed this throwaway profile with my skills” would be a nightmare of per-agent copy logic baked into the container tool. With a canonical store, it’s one line:
sm sync --copy --agent-home ~/.agentdev/profiles/research
Real directories, not symlinks — because a symlink on the host points nowhere inside a container. The store is the thing that makes isolated, reproducible agents practical instead of a copy-paste chore. Multiply that by the fan-out experiments where I’m running four agents against the same frozen task — each needing the same skills, each in its own home — and a single source of truth stops being a nicety. It’s the only sane way to run the fleet.
That’s the honest “why.” I didn’t theorize this into existence. I hit the wall enough times that the wall won.
What this is not #
Let me be clear-eyed, because I’ve got no patience for hype — especially my own.
These are draft proposals, not adopted standards. Experimental status, versioned in their own headers, comments welcome via issues and PRs. I’d genuinely rather someone tell me the design is wrong now than have me evangelize a bad one.
sm and ms are tested on Linux only. macOS has some different syntax and I’ve not gotten there since I’m all Linux now; Windows is unsupported *I think - but I don’t do Windoze so couldn’t test it even if I did grok WSL.
If you like sm and want it on your platform, pull requests are welcome. Seriously, your coding agent can build it in minutes.
And one thing I will not hand-wave: a skill is trusted code. It’s instructions an agent will follow with the agent’s own permissions. Whatever that agent is given access to has to be reviewed like the executable code it effectively is. ms flags when it’s pulling in third-party plugin skills, and records where every ingested skill came from — but the judgment is still yours. A shared store is a convenience, not an excuse to stop reading what you’re installing.
Conclusion #
The skill format converged. The skill plumbing didn’t — and the two gaps that were left are exactly the ones that paper-cut you to death once you run more than one agent: where skills live, and how a tool gives you its own. The fix is small and boring on purpose. One agent-neutral store under XDG. Tools that carry their own skill in the binary and install it with two fixed subcommands. sm to mirror the store out to agents until agents just read it themselves, and ms to get your existing skills in.
The man page was one of the best ideas UNIX ever had: the manual ships with the thing. Skills are the new man pages — so let’s rebuild that idea right this time. Once, in the open, so every tool and every agent reads from the same place.
If you want to kick the tires, the specs and the reference implementation are all linked above. And if you think I’ve got the design wrong — too simple, too XDG-flavored, missing something obvious — I actively want to hear it while it’s still a draft. Drop me a note on LinkedIn, tell me why, and pay it forward.