AI Agent Skills: Why You Need a Package Manager for Your Agents' KnowledgeAI 智能体技能：为什么你的智能体知识需要一个包管理器

Table of Contents目录

• Motivation动机
• What exactly is a skill?究竟什么是技能？
• The npm moment: a rapidly forming ecosystemnpm 时刻：正在快速形成的生态系统
• 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:相信每位软件架构师现在都非常熟悉这种状况：团队开始使用 Claude Code、GitHub Copilot 或 OpenCode 等 AI 编码智能体，随之而来的技术问题也堆积如山：

• Where do we put our coding guidelines so the agent actually follows them?我们该把编码规范放在哪里，才能确保智能体切实遵守？
• Why does team A's CLAUDE.md differ from team B's AGENTS.md?为什么 A 团队的 CLAUDE.md 和 B 团队的 AGENTS.md 不一样？
• Who copied that prompt snippet from Confluence into the repo - and is it still up to date?是谁把 Confluence 里的提示词片段复制到仓库里的？它现在还更新吗？
• How do we get our ADR conventions into every agent in the company?我们如何将 ADR（架构决策记录）规范应用到公司里的每一个智能体中？
• And wait – what is this SKILL.md file someone just committed?等等，刚才有人提交的这个 SKILL.md 文件又是什么？

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?还记得当初在项目间复制 JavaScript 文件不再具备扩展性，随后 npm 出现的那一刻吗？

We're living through that exact moment again. But this time, the "code" being shared is knowledge for AI agents.我们正在重演那一刻。只不过这一次，共享的“代码”是给 AI 智能体使用的知识。

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.一个包含 SKILL.md 文件的文件夹，其中有自然语言指令，以及可选的脚本和参考资料。

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.SKILL.md 带有包含名称和描述的 YAML 前置元数据。这样，智能体就可以发现该技能，并仅在相关时才加载它——这种模式称为“渐进式披露”，有助于保持上下文窗口的精简。

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.这正是 npm 包或 Maven 制品所做的事情。

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.Microsoft APM 在实现“真正的”依赖管理方面走得最远：你在单个 apm.yml 中声明技能、提示词、指令和 MCP 服务器，运行 apm install，锁文件（lockfile）会固定精确的版本和内容哈希。每一位开发者——以及每一台 CI 机器——都能获得字节完全一致的智能体配置。

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.OpenPackage (opkg) 正面解决了碎片化问题：这是一个开源的通用包管理器，不仅处理技能，还管理整个智能体配置生态——包括规则、斜杠命令、子智能体和 MCP 配置，并在安装时将其转换为各平台原生的约定。一个包，即可在 Claude Code、Cursor 等工具间同步。

Paks is a CLI-first package manager with a public registry and semantic versioning for skills, supporting a dozen-plus agents.Paks 是一个以 CLI 为优先的包管理器，拥有公共注册表和技能语义化版本控制，支持十多种智能体。

Tessl adds something the others lack: automated evals. Submit a skill, and it gets scored against test scenarios before it lands in the registry.Tessl 增加了一个其他工具所缺乏的功能：自动化评估。提交一个技能，它会在进入注册表之前针对测试场景进行评分。

Community registries like skills.sh round out the picture.像 skills.sh 这样的社区注册表完善了整个图景。

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.技能是一套针对自主系统的可执行指令集——这个系统会编写你的生产代码、发起拉取请求，并且在连接 MCP 服务器的情况下，还会触及你的 Jira、云端环境和数据。

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问题 1：对知识进行版本控制比对代码更难

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.如果你的“API 设计技能” v2 版本从基础 REST 风格切换为 HATEOAS 指导，那么每个安装它的智能体都会在毫无察觉的情况下开始生成不同的架构。

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问题 2：技能是提示词注入的载体

The scariest npm incidents - event-stream, left-pad, the recent waves of typosquatting - all exploited transitive trust.最可怕的 npm 事件——如 event-stream、left-pad 以及最近的恶意包冒充浪潮——都利用了传递信任。

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.仅凭指令本身就可能窃取机密或削弱智能体编写的代码。人类审查者无法察觉的隐藏 Unicode 字符，可能携带恶意载荷。

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.微软的 APM 会扫描每次安装以查找隐藏的 Unicode，并阻止未经明确声明或信任的传递性 MCP 服务器，这很能说明问题。工具作者显然预料到了这一类攻击。

My prediction: The first major "log4shell of the agent era" will not be a code vulnerability. It will be a SKILL.md.我的预测：智能体时代的第一个重大“log4shell”事件不会是代码漏洞，而会是一个 SKILL.md 文件。

Problem #3: Reproducibility becomes a compliance requirement问题 3：可重复性成为合规要求

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.没有这些，你的智能体软件开发生命周期（SDLC）中间就存在一个无法解释的黑盒。

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 boundary1. 建立内部技能注册表作为信任边界

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.在内部镜像已批准的技能。无论它是 Git 仓库、制品仓库还是新兴的注册表产品，原则比形式更重要。

2. Define ownership2. 定义所有权

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.你的“我们如何编写 ADR”技能是一个动态的架构制品。如果没人维护它，智能体就会以机器的速度忠实地复制过时的决策。

3. Review skills like code, not like docs3. 像审查代码一样审查技能，而不是像审查文档那样

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.增加自动化检查：隐藏 Unicode 扫描、机密检测，以及随着评估工具的成熟——增加回归测试，以验证技能是否仍能引导智能体朝着预期的方向工作。

4. Pin and lock everything4. 固定并锁定一切

No floating "latest" skills in CI or in shared team setups.在 CI 或共享团队配置中，禁止使用浮动的“latest”版本技能。

Adopt a lockfile-based tool (or at minimum, pin Git commit hashes) so that agent behaviour is reproducible across machines and over time.采用基于锁文件的工具（或者至少固定 Git 提交哈希），以便智能体的行为在不同机器和时间点上都是可重复的。

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.那些将技能视为一等公民、进行版本控制、明确所有权并进行审计的团队，将成倍提升他们的 AI 效能。

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.而那些任由 Markdown 文件散落在各处仓库的团队，终将通过一次次事故发现，我们当初发明包管理器是有原因的。

The npm moment for agentic skills is here.智能体技能的“npm 时刻”已经到来。