AI Agent Skills: Why You Need a Package Manager for Your Agents' Knowledge
AI agent skills are becoming a new artifact class in your AI assisted engineering. In this blog post, I explain why skill package managers are the npm moment for AI agents - and why you should treat them as an architecture topic, not a tooling gimmick.
Table of Contents
- Motivation
- What exactly is a skill?
- The npm moment: a rapidly forming ecosystem
- Why this is an architecture topic
- A pragmatic governance model
- Conclusion
Motivation
The situation that probably every software architect knows by now: your teams work with AI coding agents like Claude Code, GitHub Copilot or OpenCode - and suddenly the technical questions pile up:
- Where do we put our coding guidelines so the agent actually follows them?
- Why does team A's
CLAUDE.mddiffer from team B'sAGENTS.md? - Who copied that prompt snippet from Confluence into the repo - and is it still up to date?
- How do we get our ADR conventions into every agent in the company?
- And wait – what is this
SKILL.mdfile someone just committed?
Sound familiar?
In my role as Tech Lead and Software Architect, I see the same pattern in almost every organisation right now: valuable agent knowledge exists - but it's duplicated, unversioned, untested and invisible to any architecture governance.
We've been here before.
Remember the moment when copying JavaScript files between projects stopped scaling and npm appeared?
We're living through that exact moment again. But this time, the "code" being shared is knowledge for AI agents.
And this knowledge directly shapes what your agents build.
That's a supply chain problem. So let's treat it like one.
What exactly is a skill?
A skill, following the emerging Agent Skills specification, is deceptively simple:
A folder containing a SKILL.md file with natural-language instructions, plus optional scripts and reference material.
The SKILL.md carries YAML frontmatter with a name and a description. This way, an agent can discover the skill and load it only when it's relevant - a pattern called progressive disclosure that keeps the context window lean.
That simplicity is the point.
Because a skill is just a folder with a manifest, it can be:
- versioned like any other artifact
- shared across agents and teams
- installed with a single command
- and - crucially - audited
A folder with a manifest, metadata and installable content... - does that ring a bell?
That's exactly what an npm package or a Maven artifact is.
Which brings us to the tooling wave.
The npm moment: a rapidly forming ecosystem
Within a few months, a whole landscape of skill package managers has emerged:
Microsoft APM (Agent Package Manager) goes furthest towards "real" dependency management: you declare skills, prompts, instructions and MCP servers in a single apm.yml, run apm install, and a lockfile pins exact versions and content hashes. Every developer - and every CI machine . gets a byte-identical agent setup.
OpenPackage (opkg) attacks the fragmentation problem head-on: an open-source, universal package manager that handles not just skills but the whole zoo of agent config - rules, slash commands, subagents and MCP configs . and converts them into each platform's native conventions on install. One package, synced across Claude Code, Cursor and friends.
Paks is a CLI-first package manager with a public registry and semantic versioning for skills, supporting a dozen-plus agents.
Tessl adds something the others lack: automated evals. Submit a skill, and it gets scored against test scenarios before it lands in the registry.
Community registries like skills.sh round out the picture.
The fragmentation itself tells you where we are on the evolution curve: Skills as a concept are leaving the genesis phase, and everyone is racing to own the registry.
Because in every previous ecosystem, the registry turned out to be the point of control.
Why this is an architecture topic
Here's the uncomfortable part: A skill is not documentation.
A skill is an executable instruction set for an autonomous system - a system that writes your production code, opens pull requests and, with MCP servers attached, touches your Jira, your cloud and your data.
That means skills inherit every classic dependency problem. Plus a few new ones.
In my opinion, there are three problems you as a software architect should have on your radar:
Problem #1: Versioning knowledge is harder than versioning code
What is a breaking change in a skill?
If v2 of your "API design skill" switches from basic REST style to HATEOAS guidance, every agent that installs it silently starts producing a different architecture.
There is no compiler error.
The only symptom is drift - discovered weeks later in code review. If you're lucky.
Semantic versioning helps, but only if teams actually define what "major" means for instructions.
That's a governance decision. And it belongs to architects.
Problem #2: Skills are a prompt-injection delivery vehicle
The scariest npm incidents - event-stream, left-pad, the recent waves of typosquatting - all exploited transitive trust.
Skills make this worse: a malicious skill doesn't even need to execute code to cause damage.
Instructions alone can exfiltrate secrets or weaken the code an agent writes. Hidden Unicode characters, invisible to human reviewers, can carry payloads.
It's telling that Microsoft's APM scans every install for hidden Unicode and blocks transitive MCP servers unless they're explicitly declared or trusted. The tool authors clearly expect this attack class.
My prediction: The first major "log4shell of the agent era" will not be a code vulnerability. It will be a SKILL.md.
Problem #3: Reproducibility becomes a compliance requirement
If an agent contributed to a change, "which instructions was it running?" becomes an audit question.
Lockfiles with content hashes give you a defensible answer: this commit was produced with exactly these skills at exactly these versions.
Without that, your agentic SDLC has an unexplainable black box right in the middle.
A pragmatic governance model
In my experience, you need to make four decisions - ideally before the skill sprawl in your organisation gets worse.
1. Establish an internal skill registry as your trust boundary
Treat public skill registries exactly like public package registries: as an upstream source you curate - not as something developers pull from directly.
Mirror approved skills internally. Whether that's a Git repo, an artifact repository or one of the emerging registry products matters less than the principle.
2. Define ownership
Every skill needs an owner. Like every service does.
Your "how we write ADRs" skill is a living architecture artifact. If nobody maintains it, agents will faithfully replicate outdated decisions – at machine speed.
3. Review skills like code, not like docs
Skill changes go through pull requests with mandatory review.
Add automated checks: hidden-Unicode scanning, secret detection and - as eval tooling matures - regression tests that verify the skill still steers the agent in the intended direction.
4. Pin and lock everything
No floating "latest" skills in CI or in shared team setups.
Adopt a lockfile-based tool (or at minimum, pin Git commit hashes) so that agent behaviour is reproducible across machines and over time.
Conclusion
For twenty years, software architects have governed a well-known set of artifacts: code, configuration, infrastructure definitions, contracts.
Skills are the newest member of that family.
And arguably the most influential one - because they don't implement decisions, they generate them.
The teams that treat skills as first-class, versioned, owned and audited artifacts will compound their AI leverage.
The teams that keep them as loose Markdown files scattered across repos will discover, one incident at a time, why we invented package managers in the first place.
The npm moment for agentic skills is here.
Comments ()