The lockfile arrived for the prompt

What shipped

APM — Agent Package Manager — is a Microsoft open-source project at github.com/microsoft/apm, MIT-licensed, showing 4.3k GitHub stars. Its README describes it as "an open-source, community-driven dependency manager for AI agents," and the mental model it offers is explicit: a package.json for agent configuration. You declare instructions, skills, prompts, agent files, hooks, plugins and MCP servers in one apm.yml, and apm install materialises them into whichever agent tools you listed.

Sources are deliberately unbounded — packages install from GitHub, GitLab, Bitbucket, Azure DevOps, Gitea, or "any git host" — and versions pin with a ref, as in microsoft/apm-sample-package#v1.0.0. It builds on three open standards it does not own: AGENTS.md, Agent Skills, and MCP. There is no central registry, which is a design choice with consequences we will come back to.

The README's own framing is the most important sentence in it

Buried in the security section is a line that does more analytical work than the rest of the documentation combined: "Agent context is executable in effect — a prompt is a program for an LLM."

That is correct, it is the right justification for building this tool at all, and it is unusual to see a vendor say it plainly. If instructions are programs, then shipping them around without versioning, pinning or provenance is obviously reckless, and the absence of any dependency management for agent configuration has been a real gap. A team that pulls a skill from a GitHub repository today has no record of which commit they got, no way to detect that someone edited it in place afterwards, and nothing to hand a procurement reviewer. APM closes all three of those.

The framing also sets up the limit, though, and the limit is where the package-manager analogy stops holding. A conventional dependency is a program whose behaviour is bounded by the runtime that executes it: a library runs inside a process with a filesystem, a permission set and a syscall boundary. Reviewing it means reasoning about code against those bounds. Agent context has no equivalent bound, because its "execution" is a model's interpretation of prose in a particular harness with a particular toolset. The same skill file is inert in one configuration and a data-exfiltration path in another.

So the unit a hash pins — the file — is not the unit that determines behaviour. The behaviour is a property of the composition: this prose, that model, those tools, that permission set. Nothing in a lockfile describes a composition, and this is not a defect in APM's implementation. It is a category difference between code and context that the npm analogy quietly obscures.

What the lockfile genuinely buys

Three of these are worth adopting on their own merits, independent of the safety argument.

Drift detection is the underrated one. apm audit catches hand-edits to generated context, and apm audit --ci turns that into a branch-protection gate. In practice the most common way a reviewed agent configuration stops matching what was reviewed is not an attack — it is someone adding a line to a Copilot instructions file at 18:00 to make a demo work. A drift check converts an invisible divergence into a failing build, which is the same move CI made for formatting and types.

Transitive MCP consent is a correct default. The README states that transitive MCP servers require explicit consent. That is the right call: a package that silently brings along an MCP server is adding tools to your agent's reach, which is an authority change disguised as a dependency change — exactly the hazard in agent supply-chain security.

SBOM export, with APM's own caveat attached. The documentation calls the export "provenance for procurement, not a compliance attestation," which is an unusually precise self-limitation and should be quoted back whenever someone treats a CycloneDX file as evidence of review.

The hidden-Unicode scan at install time also deserves a mention, because invisible characters in instruction files are a real and specific attack — and because it illustrates the shape of what install-time scanning can do. It catches a known encoding trick. It does not read the English.

One install, nine harnesses, and a boundary that comes later

APM's supported targets are GitHub Copilot, Claude Code, Grok Build, Cursor, OpenCode, Codex, Gemini, Windsurf and Kiro. That breadth is the product's main convenience and also the place its risk concentrates, for two reasons that compound.

First, a single apm install writes into every target the manifest lists. The pre-APM situation — a skill pasted into one tool by one developer — had terrible provenance and a naturally small blast radius. A manifest committed to a repository has excellent provenance and writes to every harness every contributor uses. Better auditing and wider reach arrive in the same commit, and only one of them is in the release notes. The general version of this is blast radius.

Second, what gets written lands in the files a harness reads at startup to constitute itself — instruction files, rules, hooks, tool configuration. Those are consumed before any sandbox or permission decision is made, because they are partly what decides the permissions. A sandbox contains what an agent does; it does not vet what the agent was told it is for. APM's documentation draws this line itself, noting that the policy file governs what gets installed while the agent harness governs what runs — a distinction worth taking literally. The attack surface of the configuration layer specifically is in harness configuration injection.

The no-central-registry choice matters here too. Installing from any git host means there is no chokepoint where a package could be scanned, delisted or revoked by anyone other than its host. Compare the MCP side of the ecosystem, where distribution and registries are a live design question — see MCP registry & distribution. "Install from anywhere" is a reasonable trade for a tool aimed at enterprises with internal git, and it does mean a revoked package stays installable from a fork.

The part that is still a person reading English

Strip away the machinery and the remaining question is the one that was always hard: should this instruction file be in my agent's context at all? A pinned hash answers "is this the file I looked at." It cannot answer "does this file, read by this model, with these tools available, cause something I would not authorise."

Three failure shapes survive a perfect lockfile untouched. A package can be benign at review and harmful in composition — an instruction to always read configuration files before answering is helpful in a documentation skill and an exfiltration primitive next to a tool with network egress. It can be benign at v1.0.0 and harmful at v1.1.0, where pinning helps only if you actually re-review on bump rather than letting a bot raise and merge it. And it can be harmful in a way that reads as competent prose, which is the case install-time scanning is structurally unable to reach: there is no encoding trick to detect, just a sentence that does something you did not want.

This is why the pre-existing advice does not change. Read the package. The procedure for doing that is in vetting a third-party skill, and the reason prose is dangerous in the first place is prompt injection. What APM changes is that after you have read it, you can prove what you read and be told when it stops matching — which is a genuine improvement over the status quo of neither.

What to change this week

Adopt the parts that are pure upside, and do not let the lockfile stand in for a review you did not do.

• Commit a lockfile even if you adopt nothing else. Whatever manages your agent configuration, the baseline is a record of which commit of which skill you are running. Pin refs to immutable tags, not branches — a ref that moves makes the hash a record of history rather than a constraint.
• Put the drift check in CI before you add a single third-party package. The first thing it will catch is your own team, and that is the finding worth having.
• Treat a version bump as a diff to read, not a dependency to update. If your bot can merge an agent-context bump without a human reading the prose, you have automated exactly the step the lockfile exists to make reviewable.
• Review at the composition, not the file. Ask what tools are reachable in the harness this lands in. The same package warrants different answers in a sandboxed CI agent and on a developer's workstation with production credentials — see agents on developer workstations.
• Narrow your targets. Listing nine harnesses because they are supported means one merged package reaches all nine. List the ones you actually use.
• Keep the SBOM in the box APM puts it in. Provenance for procurement. If a reviewer accepts it as an attestation of safety, correct them, because the documentation already does.

The larger point is that this is what maturing infrastructure looks like, and it is good news: the ecosystem has moved from "agent configuration is a file somebody pasted" to "agent configuration is a dependency with a lockfile." That is a real step. It just relocates the hard problem rather than solving it — the reading was always the work, and now you can prove you did it.

Further reading

On this wiki:

• Vetting a Third-Party Skill — the review the lockfile cannot do for you.
• Agent Supply-Chain Security — where a dependency change is really an authority change.
• Harness Configuration Injection — why the config layer sits outside the sandbox.
• Skills vs Subagents vs MCP vs Hooks — what each of the things in an apm.yml actually is.
• Tool Catalog Lifecycle — managing the inventory over time.
• Agent Skills — the standard APM builds on.

Sources:

• microsoft/apm — the repository, MIT-licensed.
• microsoft/apm README — manifest, lockfile, audit, policy and security text quoted above.
• microsoft/homebrew-apm — the Homebrew tap.