{"slug": "skills-are-the-new-man-pages", "title": "Skills Are the New Man Pages", "summary": "Software engineer and blogger Gherlein published two independent IETF-Internet-Draft-style proposals for a Skill Self-Installation Specification, under which a conforming command-line tool embeds its own agent skill in the executable and exposes fixed `install-skill` and `print-skill` subcommands so an AI agent can read how to drive an unseen binary with nothing installed. The drafts, hosted at github.com/gherlein/skill-embedding-standard, build on the converging `SKILL.md` directory format that major agents mostly agree on, and address the two unstandardized pieces around it: how a tool hands over its own skill and where that skill is stored. Gherlein, who built the dot-agents tool to run the same skills across Claude Code and Mario Zechner's pi, argues the fixed subcommand names make installation discoverable, framing skills as the machine-readable successor to man pages.", "body_md": "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.**\n\nI 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*](https://archive.org/details/linuxmanessentia0000unse), 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.\n\nBut 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](https://agentskills.io/).\n\nMan pages taught people. Skills teach agents. Same job, new reader.\n\nSo 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.\n\nThe skill *format* is already converging — it’s a directory with a [`SKILL.md`](https://agentskills.io/) 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](https://github.com/gherlein/skill-embedding-standard) — 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.\n\n## Start with the tool carrying its own skill\n\nThis is the man-page half, and it’s the part I’m most excited about. The [Skill Self-Installation Specification](https://github.com/gherlein/skill-embedding-standard/blob/main/SKILL-INSTALL-SPEC.md) 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:\n\n| Subcommand | Does | \n|---|---|\n| `install-skill` | Writes the carried skill into the shared store, ready for any agent. | \n| `print-skill` | Prints the carried skill to stdout. | \n\nThe 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.\n\n## But where does the tool write it?\n\n`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.\n\nI’ve written before that [the tooling is the new model](https://blog.herlein.com/post/dot-agents/) — that the workflow around the agent matters more than which brain is underneath. I built [dot-agents](https://github.com/gherlein/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.\n\nAnd 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](https://blog.herlein.com/post/ai-agents-in-trenchcoats/). 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.\n\nBecause 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.\n\nHere’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](https://blog.herlein.com/post/ai-agents-in-trenchcoats/) — 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.\n\nSo 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.\n\nSo — 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.\n\n## A standard place — and a way to fan it out\n\nThe [Skills Directory Specification](https://github.com/gherlein/skill-embedding-standard/blob/main/SKILLS-DIRECTORY-SPEC.md) 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:\n\n```\n${XDG_DATA_HOME:-~/.local/share}/skills/<name>/SKILL.md\n```\n\nOne 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.\n\nThe 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.)\n\n## The companion tool: sm (and ms)\n\nA spec nobody implements is a blog post with delusions of grandeur. So there’s a reference implementation: **[`sm` and `ms`](https://github.com/gherlein/sm)** (skills-mapper), two small Go binaries that do exactly the bridging I just described — and nothing more.\n\nskills-mapper: one central burrow, tunnels to every agent.\n\n- **`sm`** goes*store to agents* . Until agents read the XDG store natively,`sm sync` mirrors it into each agent’s proprietary folder — symlinks by default, or real copies with`--copy` for 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 does**not** populate the store, fetch anything, or transform skills.\n- **`ms`** goes the other direction — the on-ramp. It ingests the skills you*already* 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. Run`ms` once, then let`sm` fan everything out to the rest.\n\n```\nflowchart LR\n    existing[\"skills an agent<br/>already has\"] -- \"ms (one-time ingest)\" --> store\n    producers[\"producers:<br/>git clone, .deb, embedded binary\"] -- write --> store[\"canonical store<br/>~/.local/share/skills/&lt;name&gt;\"]\n    store -- \"sm sync\" --> claude[\"~/.claude/skills\"]\n    store -- \"sm sync\" --> copilot[\"~/.copilot/skills\"]\n    store -- \"sm sync\" --> others[\"pi · oh-my-pi · hax · kit\"]\n```\n\nThe 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.\n\nAnd 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.\n\n## Where this really bit me: isolated agents\n\nHere’s the case that turned this from “mildly annoying” into “okay, I’m writing a standard.”\n\nI’ve been building a thing I’m calling [agentdev](https://github.com/gherlein/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.\n\nA 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:\n\n```\nsm sync --copy --agent-home ~/.agentdev/profiles/research\n```\n\nReal 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](https://blog.herlein.com/post/ai-agents-in-trenchcoats/) 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.\n\nThat’s the honest “why.” I didn’t theorize this into existence. I hit the wall enough times that the wall won.\n\n## What this is not\n\nLet me be clear-eyed, because I’ve got no patience for hype — especially my own.\n\nThese 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.\n\n`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.\n\nIf you like sm and want it on your platform, pull requests are welcome. Seriously, your coding agent can build it in minutes.\n\nAnd 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.\n\n## Conclusion\n\nThe 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.\n\nThe 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.\n\nIf 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](https://www.linkedin.com/in/gherlein/), tell me why, and pay it forward.", "url": "https://wpnews.pro/news/skills-are-the-new-man-pages", "canonical_source": "https://blog.herlein.com/post/skills-are-the-new-man-pages/", "published_at": "2026-10-27 08:00:01+00:00", "updated_at": "2026-10-28 02:42:58.362383+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "ai-tools", "developer-tools"], "entities": ["Gherlein", "Skill Self-Installation Specification", "agentskills.io", "dot-agents", "Claude Code", "Mario Zechner", "pi"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/skills-are-the-new-man-pages", "markdown": "https://wpnews.pro/news/skills-are-the-new-man-pages.md", "text": "https://wpnews.pro/news/skills-are-the-new-man-pages.txt", "jsonld": "https://wpnews.pro/news/skills-are-the-new-man-pages.jsonld"}}