On Sunday evening someone posted a short question to Hacker News: how do you manage skills files? Roughly sixty answers arrived over the following day. The interesting part was not the disagreement about whether skills are worth having. It was that a dozen developers, independently and mostly without reference to each other, described building the same missing tool.
TL;DR
- A Hacker News thread on managing agent skills files surfaced at least six separately built package managers for them, including one created the day before the thread.
- The format is deliberately trivial: a
SKILL.mdfile withnameanddescriptionin YAML frontmatter, loaded progressively at roughly 100 tokens per skill until triggered. - Distribution is the unsolved half, and the vendor documents the gap: custom Skills do not sync across surfaces, and claude.ai offers no centralised admin management or organisation-wide distribution.
- A skills file is a code-generating artefact carrying none of the controls you apply to code: no lockfile, no review gate, no test, no expiry date.
- Two risks nobody in the thread raised: Agent Skills sit outside zero data retention arrangements, and a global skills folder applies one client’s conventions inside another client’s repository.
Everyone in that thread built the same tool
osrim/ski, described by its author as a package manager for agent skills, created on 5 September, the day before the thread. vercel-labs/skills, past thirty thousand stars, installing with npx skills add owner/repo. withastro/rosie, whose entire description is “Agent package manager”. capshelf, which pins each skill’s content hash so an upstream edit cannot quietly change behaviour. agent-plugins.org, a vendor-neutral 1.0.0 specification whose stated rationale is that clients invented incompatible formats for identical components.
Beyond the published tools, respondents described chezmoi, Nix home-manager, Guix Home, symlink farms, bootstrap scripts wired into session-start hooks, a Go binary that syncs skills across harnesses, and a command-line tool with the skills compiled into the binary so that copying one file moves the whole library to a new machine. One respondent works for the Norwegian Labour and Welfare Administration, which publishes a public registry of 73 agent customisations sorted across eight domains, with adoption statistics attached.
When that many capable people build the same thing in parallel, it stops being a matter of workflow taste. It is a missing primitive.
The vendor documents the gap
The format itself was never the hard part. A skill is a directory with a SKILL.md file, YAML frontmatter carrying a name (64 characters maximum) and a description (1,024 maximum), and whatever markdown, reference files or scripts you bundle alongside. Loading is progressive: metadata sits in the system prompt at roughly 100 tokens per skill, the body loads only when the description matches your request, and bundled resources cost nothing until read.
Distribution was left open, and Anthropic’s own documentation is candid about it. Custom Skills do not sync across surfaces, so a skill uploaded to claude.ai is not available through the API. Sharing scope differs by surface: individual on claude.ai, workspace-wide on the API, personal (~/.claude/skills/) or project (.claude/skills/) in Claude Code. The documentation states plainly that claude.ai does not support centralised admin management or organisation-wide distribution of custom Skills. Every hand-rolled sync script in that thread exists to fill exactly that sentence.
A skill is a dependency that writes your code
Here is the property that makes this an engineering governance question rather than a tidiness question. A skill does not perform one task once. It changes how everything gets built afterwards. One respondent stated the risk more precisely than any vendor documentation does: a mistake in the skills repository spreads into all of the new code written with it.
That is a fan-out no ordinary internal document has. A wrong line in a runbook misleads whoever reads it that morning; a wrong line in a skill produces the wrong pattern in every repository where it is installed, for as long as it stays installed, and produces it confidently.
Now compare the treatment given to far less consequential dependencies. An npm package arrives with a version, a lockfile, an integrity hash and, in most teams, a pull request when it moves. A container image is pinned by digest. The file that tells your agent how to write your code is copied out of somebody’s main branch, refreshed by a startup hook, and updated without anyone seeing a diff. Across sixty answers, one person mentioned pinning content hashes.
The failure mode is worse for being quiet. A skill that has drifted out of step with the codebase does not throw an error and nothing fails to compile. The agent reads instructions describing last quarter’s conventions and writes code that matches them, and the only signal is a reviewer noticing that a pattern looks slightly dated. Two respondents had a structural answer: one runs a scheduled agentic job that compares skills against the documentation and opens pull requests where they have diverged, another treats skills as testable and writes evals for them. Nearly everyone else answered the question of how they know their skills still work with trial and error.
Two risks nobody raised
The first is confidentiality. The entire value of a bespoke skill is that it holds insider knowledge, and the clearest example in the thread was blunt: rather than have the agent rummage through the .ssh directory working out how to reach a server, the skill states which key and which user. It is useful because it is specific, which is another way of saying that a mature skills library is a written description of your infrastructure, and of your clients’ infrastructure. Several respondents keep skills in dotfiles repositories, and one keeps a public repository and a private one side by side. Worth knowing before you make that split: Anthropic’s documentation states that Agent Skills is not covered by zero data retention arrangements, and that skill definitions and execution data are retained under standard policy. If a skill names a client’s systems, that should be a decision, not a discovery.
The second is contamination across clients. Personal skills in ~/.claude/skills/ apply everywhere you work. For an in-house team on a single product, that is exactly right, and it is the model most of the thread assumes. For an agency it means one client’s commit conventions, branch naming, testing philosophy and architectural preferences travel silently into another client’s repository. Project scoping exists for precisely this reason: .claude/skills/ lives in the repository, gets reviewed with the repository, and leaves when the engagement ends.
The case against, which is stronger than it looks
Not everyone in the thread thinks any of this matters. One respondent reported skills becoming less effective with each model release and replaced the library entirely with a deterministic harness: where a task can be expressed as code, write the code and let the agent call it. Another keeps nine skills and observes that people with hundreds installed from marketplaces lose track of what they have and stop using any of it.
Both are right about general-purpose skills. A code review or design critique skill is guidance the model already carries, and paying for it in permanent context is a poor trade that gets worse with every release. What survives is the contextual half: the conventions, the quirks, the historical accidents that no training set contains. That half is not downloadable, which is exactly why it needs governing.
What we would actually do
- One repository, installed by pinned version. Not a symlink to main, not a hook quietly pulling the latest on session start. If a file changes the way your code gets written, the change belongs in a diff somebody approved.
- Scope by client, for the reason above. The global folder is for personal habits only.
- Treat marketplace skills as third-party code. We covered fake repositories and poisoned agent registries earlier this year and the guidance has not softened: read the whole bundle, scripts included, or do not install it.
- Test the ones you rely on. A saved prompt with a known-good outcome, re-run whenever the skill changes, catches the drift that careful writing does not prevent.
- Give each skill an owner and a review date. A skill with no name against it is a document nobody is responsible for keeping true.
The thread reads like a question about workflow. It is closer to an early photograph of a supply chain forming, at the stage where everyone is still writing their own installer.
One caveat carries over from our earlier work on agent instructions: instructions are not controls. A skills library is guidance the model usually follows, not a constraint it cannot breach, which is what makes governing where that guidance comes from the part you can actually enforce.
We build and operate agent tooling for development teams, including the unglamorous parts of governing it. If your team’s skills folder is currently a symlink and a hope, get in touch.
📷 Photo by Anton Savinov on Unsplash
