Microsoft APM: Agent Package Manager for reproducible agent context

microsoft/apm is Microsoft's Agent Package Manager (APM): a manifest-driven way to install and share everything an AI coding agent needs in a repo—skills, MCP servers, plugins, prompts, hooks, and related primitives—so newcomers get a reproducible stack after git clone, not a wiki of manual setup steps.

Primary sources: GitHub — microsoft/apm · Documentation site

This note is a builder-oriented summary of what APM claims to solve, how it compares to ad-hoc npx skills add flows, and where ExplainX readers already have parallel concepts (skills registry, MCP directory).

Quick reference

Treat versioned behavior against the release you install; the project ships tagged releases (for example v0.10.x in recent history).

Mental model: package.json, but for agents

APM's pitch is deliberately familiar:

• You declare dependencies in apm.yml
• You apm install to materialize files and wire supported clients
• Transitive packages resolve like npm/pip-style trees
• A lockfile records what was actually resolved

That matters because agent "dependencies" are not just libraries—they are instructions and tool wiring that change model behavior. Treating them like versioned supply chain is closer to how security teams already think about code.

Example manifest shape (from upstream README)

The README illustrates apm.yml mixing APM-packaged skills, plugins, agent markdown, full packages, and MCP servers:

name: your-project
version: 1.0.0
dependencies:
  apm:
    - anthropics/skills/skills/frontend-design
    - github/awesome-copilot/plugins/context-engineering
    - github/awesome-copilot/agents/api-architect.agent.md
    - microsoft/apm-sample-package#v1.0.0
  mcp:
    - name: io.github.github/github-mcp-server
      transport: http

After clone:

apm install

Upstream positions this as one command to align Copilot, Claude, Cursor, OpenCode, Codex, and Gemini installs—with client-specific caveats called out in docs (notably around MCP transports and Codex).

"Coming from npx skills add?"

The README now includes an explicit conversion block. The idea:

apm install vercel-labs/agent-skills
apm install vercel-labs/agent-skills --skill deploy-to-vercel

Same install gesture, plus you keep a manifest, lockfile, and policy hooks if your org adopts them.

On ExplainX, many teams still discover skills through the registry UI; APM is complementary infrastructure for repo-first workflows. Start with our agent skills guide if the vocabulary is new.

Security and governance (what enterprises will care about)

APM's README groups value into portability, secure defaults, and governance. Under the security column, it highlights:

• Reproducibility — manifest + lockfile with hashed resolution
• Install-time checks — scanning for content that can subvert agent parsing (upstream cites hidden Unicode-style risks)
• MCP trust — transitive MCP installs gated behind explicit consent
• Policy hooks — apm-policy.yml for allowlists and inheritance patterns, plus CI audit integration (for example branch protection workflows)

None of that removes the need for human review on high-risk repos; it raises the floor. For threat framing, see agent skills security.

Installation (official scripts)

Upstream documents:

Linux / macOS

curl -sSL https://aka.ms/apm-unix | sh

Windows

irm https://aka.ms/apm-windows | iex

Then add packages (apm install ...), marketplaces, or MCP targets (apm install --mcp ...). Always read Microsoft's Getting Started on microsoft.github.io/apm before running remote installers in regulated environments.

agentrc and shared instruction formats

The README ties APM to agentrc: generate repo-grounded instructions from code, then package them for org-wide reuse. The .instructions.md format is called out as shared—useful when you want mechanical truth (build commands, conventions) combined with curated skills from publishers you trust.

How this fits ExplainX's broader map

Vendor skill bundles such as google/skills are exactly the kind of upstream you might pin by version once APM's resolution story matches your compliance needs.

Deep dive: APM installation and configuration workflow

Understanding APM's installation flow helps teams integrate it into existing CI/CD pipelines and developer onboarding processes. The following sections break down the end-to-end workflow from initial setup to production deployment.

Installation options and environment setup

APM supports multiple installation methods to accommodate different team preferences and security policies. Beyond the quick-start scripts shown earlier, teams running in air-gapped or highly regulated environments can clone the repository and build from source:

git clone https://github.com/microsoft/apm.git
cd apm
npm install
npm run build
npm link

This approach gives you full control over the binary, allows internal security scanning before deployment, and enables customization of default behaviors through environment variables.

Environment variables for APM:

• APM_REGISTRY_URL — point to an internal registry mirror for air-gapped environments
• APM_CACHE_DIR — customize where APM stores downloaded packages (default: ~/.apm/cache)
• APM_POLICY_PATH — override the default apm-policy.yml location for centralized governance
• APM_INSTALL_CONCURRENCY — control parallel downloads (useful for bandwidth-constrained networks)

Teams with strict security requirements often mirror the public APM registry internally. The registry protocol is documented in the APM specification, allowing enterprises to run private registries with the same tooling.

Creating your first apm.yml manifest

A production-ready apm.yml goes beyond the basic example in the README. Here is a more comprehensive structure that teams use in real repositories:

name: my-production-app
version: 2.1.0
description: "Production agent stack for API platform"

# Runtime environment constraints
engines:
  apm: ">=0.10.0"
  node: ">=20.0.0"

# Agent dependencies organized by category
dependencies:
  apm:
    # Code review and quality
    - anthropics/skills/skills/code-review#v2.3.0
    - github/awesome-copilot/plugins/security-scanner#v1.5.1

    # Domain-specific agents
    - my-org/internal-api-architect#v3.0.0
    - my-org/database-migration-helper#v1.2.0

    # Full skill packages with transitive deps
    - vercel-labs/agent-skills#v0.8.0

  mcp:
    # Production database access (read-only)
    - name: io.company.internal/postgres-mcp
      transport: stdio
      config:
        connection_string: "${DATABASE_URL_READ_REPLICA}"
        max_query_time: 30s

    # GitHub integration
    - name: io.github.github/github-mcp-server
      transport: http
      config:
        api_token: "${GITHUB_TOKEN}"
        org_filter: "my-org"

# Development-only dependencies
devDependencies:
  apm:
    - my-org/local-testing-tools#v0.5.0
  mcp:
    - name: io.company.internal/mock-services
      transport: stdio

# Workspace configuration for monorepos
workspaces:
  - "packages/*"
  - "services/*"

# Scripts for common tasks
scripts:
  postinstall: "apm generate-docs"
  verify: "apm audit --policy strict"
  sync: "apm sync --all-clients"

This structure mirrors package.json conventions, making it immediately familiar to JavaScript developers while adding agent-specific features like MCP server configuration and multi-client sync commands.

Understanding the lockfile: apm.lock.yaml

The lockfile is APM's reproducibility guarantee. Every apm install generates or updates apm.lock.yaml, recording the exact resolved versions, source URLs, and integrity hashes. Here is what a lockfile entry looks like:

dependencies:
  anthropics/skills/skills/code-review:
    version: 2.3.0
    resolved: https://registry.apm.ms/anthropics/skills/skills/code-review/-/code-review-2.3.0.tgz
    integrity: sha512-abc123...xyz789
    dependencies:
      anthropics/skills/core-utils:
        version: 1.1.0
        resolved: https://registry.apm.ms/anthropics/skills/core-utils/-/core-utils-1.1.0.tgz
        integrity: sha512-def456...uvw012

  io.github.github/github-mcp-server:
    version: 1.2.3
    resolved: https://registry.apm.ms/mcp/github/-/github-mcp-server-1.2.3.tgz
    integrity: sha512-ghi789...rst345
    transport: http
    requires_consent: true

The lockfile serves multiple purposes in production workflows:

1. Deterministic installs: New team members get exactly the same agent setup as everyone else, eliminating "works on my machine" issues for agent tooling.

2. Security auditing: The integrity field uses SHA-512 hashing, allowing security teams to verify that downloaded packages match what was originally vetted.

3. Supply chain visibility: The resolved URLs create an audit trail of where every agent capability came from, critical for SOC 2 and similar compliance frameworks.

4. Change detection: In pull requests, lockfile diffs immediately show which agent dependencies changed, triggering security review workflows.

Teams committed to reproducibility should always commit apm.lock.yaml to version control and treat it as a critical security artifact—changes should go through the same review process as code changes.

Workspace and monorepo support

Large organizations often structure code as monorepos with dozens of services. APM's workspace feature allows you to declare agent dependencies once at the root and selectively override them in individual packages:

Root apm.yml:

name: company-monorepo
version: 1.0.0
workspaces:
  - "services/*"
  - "packages/*"
dependencies:
  apm:
    - my-org/base-coding-standards#v5.0.0

services/api/apm.yml:

name: api-service
version: 2.0.0
dependencies:
  apm:
    - my-org/api-design-agent#v3.0.0
    - my-org/security-hardening#v1.0.0
  mcp:
    - name: io.company.internal/api-gateway-mcp
      transport: http

Running apm install at the root resolves all workspace dependencies in a single pass, deduplicating shared skills and generating one unified lockfile. This approach dramatically reduces install times and ensures consistency across services.

Advanced use cases and real-world implementations

Enterprise governance with apm-policy.yml

The policy file is where APM differentiates itself from ad-hoc skill installation. Organizations use apm-policy.yml to enforce standards across hundreds of repositories:

version: 1
name: "company-wide-agent-policy"

# Allowlist approach: only these registries are permitted
registries:
  allowed:
    - "https://registry.apm.ms"
    - "https://internal-registry.company.com"
  blocked:
    - "https://untrusted-source.example"

# Package-level controls
packages:
  allowed:
    - "my-org/*"              # All internal packages
    - "anthropics/skills/*"   # Vetted external vendor
    - "github/awesome-copilot/*"
  blocked:
    - "*/experimental/*"      # Block experimental packages
    - "untrusted-author/*"

# MCP server restrictions
mcp:
  require_explicit_consent: true
  allowed_transports:
    - "stdio"
    - "http"  # Only if endpoint is internal
  blocked_transports:
    - "ws"    # WebSocket blocked for security

  endpoint_rules:
    - pattern: "*.company.com"
      allow: true
    - pattern: "*"
      allow: false  # Block all external endpoints

# Audit and compliance
audit:
  severity_threshold: "medium"  # Fail CI on medium+ vulnerabilities
  ignore_advisories:
    - "APM-2024-001"  # Known false positive, exception approved 2026-03-15

# Inheritance for organizational units
extends:
  - "https://central-governance.company.com/base-policy.yml"

Policy files support inheritance, allowing a central security team to define baseline rules while individual business units layer additional constraints. The apm audit command respects these policies, making it straightforward to integrate into CI:

# .github/workflows/agent-dependencies.yml
name: APM Security Audit
on: [pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install APM
        run: curl -sSL https://aka.ms/apm-unix | sh
      - name: Audit dependencies
        run: apm audit --policy strict --json > audit-report.json
      - name: Check for violations
        run: |
          if [ $(jq '.violations | length' audit-report.json) -gt 0 ]; then
            echo "Policy violations detected"
            jq '.violations' audit-report.json
            exit 1
          fi

This workflow blocks merges if any package violates organizational policy, closing a major security gap in agent-driven development.

Multi-client synchronization strategies

One of APM's most powerful features is installing the same manifest across multiple agent clients. However, clients have different capabilities—not every feature works everywhere. Here is how to handle these differences:

# apm.yml with client-specific configuration
name: cross-platform-project
version: 1.0.0
dependencies:
  apm:
    - anthropics/skills/skills/code-review

  mcp:
    - name: io.github.github/github-mcp-server
      transport: http
      clients:
        claude-code:
          enabled: true
          config:
            max_rate: 100
        cursor:
          enabled: true
          config:
            max_rate: 50
        codex:
          enabled: false  # Codex has MCP limitations per README
          fallback: "use-apm-skill-equivalent"

The apm sync command respects these client constraints:

# Sync to all supported clients
apm sync --all-clients

# Sync to specific client
apm sync --client claude-code

# Dry run to see what would change
apm sync --all-clients --dry-run

For organizations standardizing on one primary client (typically Claude Code or GitHub Copilot), the recommendation is to optimize the manifest for that client and use sync as a best-effort compatibility layer for teams using alternatives.

Integrating with existing skill workflows

Many teams already use npx skills add or manual skill installation. APM provides migration paths that preserve existing workflows while adding reproducibility:

Migration strategy 1: Parallel adoption Keep existing ad-hoc skills in .claude/skills/ and introduce APM for new, shared skills. APM will not touch manually installed skills unless they conflict with manifest entries.

Migration strategy 2: Audit and codify Run apm import (if available in your version) to scan existing skill directories and generate an apm.yml that matches your current state:

apm import --from ~/.claude/skills --generate apm.yml

Review the generated manifest, pin versions, and commit it. Future installs will be reproducible.

Migration strategy 3: Gradual replacement Document a transition period where both installation methods are acceptable, then deprecate manual installation once APM is proven in production. Use policy files to enforce the transition:

# apm-policy.yml during transition
audit:
  warnings:
    - "Manual skills detected in .claude/skills/manual-*"
    - "Migrate to apm.yml before 2026-09-01"

Performance optimization and caching

APM's caching strategy significantly impacts install times, especially in CI environments. Understanding the cache hierarchy helps optimize builds:

Cache layers

1. Local cache (~/.apm/cache): Stores downloaded packages for reuse across projects on the same machine.

2. Content-addressable storage: Packages are stored by integrity hash, enabling safe sharing even across different manifest versions.

3. Registry CDN: The public registry uses a global CDN to reduce latency; check APM_REGISTRY_URL for your region.

CI/CD caching best practices

# GitHub Actions example with APM caching
- name: Cache APM packages
  uses: actions/cache@v4
  with:
    path: ~/.apm/cache
    key: apm-${{ runner.os }}-${{ hashFiles('**/apm.lock.yaml') }}
    restore-keys: |
      apm-${{ runner.os }}-

- name: Install APM dependencies
  run: apm install --frozen-lockfile

The --frozen-lockfile flag fails the build if apm.yml changes without updating the lockfile, preventing accidental dependency drift in production.

For large monorepos, consider splitting the cache by workspace to parallelize installations:

# Install workspaces in parallel
apm install --workspace services/api &
apm install --workspace services/worker &
wait

Offline and air-gapped environments

Organizations with air-gapped networks can mirror the APM registry:

1. Set up an internal registry using the APM registry protocol (documented at microsoft.github.io/apm/registry-protocol).

2. Populate the mirror by downloading all required packages to an internet-connected machine, then transferring to the internal network.

3. Configure clients to use the internal registry:

apm config set registry https://internal-registry.company.com

4. Verify integrity of mirrored packages using the lockfile hashes before trusting them in production.

Some enterprises run a "registry proxy" that caches packages on first request, simplifying ongoing maintenance while preserving air-gap security for sensitive environments.

Security considerations and threat modeling

APM's security model addresses several attack vectors unique to agent dependencies. Understanding these threats helps teams make informed risk decisions.

Supply chain attacks

Agent skills have elevated privileges—they can read code, modify files, and interact with external services. A compromised skill in your dependency tree is a critical vulnerability. APM mitigates this through:

Integrity verification: Every package is hashed, and APM verifies the hash before extraction. This prevents tampering in transit or in the registry.

Transitive dependency visibility: The lockfile exposes the entire dependency graph. Security teams should audit not just direct dependencies but also what those dependencies pull in.

Policy enforcement: Allowlists in apm-policy.yml limit which packages can be installed, reducing the attack surface.

Example threat scenario: An attacker compromises a popular skill package and publishes a malicious version. Without APM, developers running npx skills add might pull the compromised version. With APM and a committed lockfile, the malicious version is only installed if someone explicitly updates the manifest and the lockfile—triggering code review.

MCP server trust boundaries

MCP servers are especially sensitive because they provide runtime tool access to models. APM requires explicit consent for transitive MCP dependencies:

mcp:
  - name: io.github.some-org/data-fetcher
    transport: http
    requires_consent: true  # User must acknowledge on first install
    consent_message: "This MCP server will access internal APIs"

When a skill transitively depends on an MCP server, APM prompts the user to review and approve before installation proceeds. This consent flow is critical—it prevents skills from silently introducing new tool access.

Content scanning and hidden risks

The README mentions install-time scanning for "hidden Unicode" and similar attack vectors. These are subtle but dangerous:

• Hidden Unicode: Attackers embed invisible characters in skill instructions that change model behavior in unexpected ways.
• Prompt injection: Malicious skills contain instructions designed to manipulate the model into executing unintended actions.
• Exfiltration attempts: Skills that encode sensitive data in error messages or logs.

APM's content scanner flags these patterns, but it is not foolproof. Teams handling sensitive data should:

1. Review all skill content before adding to the manifest, especially for external packages.
2. Run skills in sandboxed environments where data exfiltration is blocked.
3. Monitor agent behavior for anomalies using observability tools.

Audit workflows for compliance

Many regulated industries require audit trails for all software components. APM supports this through:

Provenance logging: Every apm install can emit a provenance record in SLSA format (if configured), documenting who installed what, when, from where.

Change approval workflows: Integrate apm audit into pull request checks so that dependency changes require security team sign-off.

Vulnerability scanning: APM can integrate with vulnerability databases (future feature per roadmap) to flag known-bad package versions.

Sample compliance workflow:

# In CI: Generate and store provenance
apm install --provenance > provenance.jsonl
aws s3 cp provenance.jsonl s3://compliance-logs/apm/$(date +%Y-%m-%d)/

# Audit against policy
apm audit --policy strict --output compliance-report.json

# Require security team review for MCP changes
if git diff main -- apm.lock.yaml | grep -q "mcp:"; then
  echo "MCP dependency change detected - security review required"
  gh pr edit --add-label security-review
fi

Comparing APM to alternative approaches

Understanding where APM fits in the broader ecosystem helps teams decide whether to adopt it.

APM vs npx skills add

The classic npx skills add workflow is simple and immediate—perfect for exploration. However, it lacks reproducibility. If you onboard a new developer, they must manually run the same sequence of npx skills add commands, and version drift is inevitable.

When to use npx:

• Solo projects
• Rapid prototyping
• Learning and experimentation

When to use APM:

• Team projects with multiple developers
• Production deployments
• Environments requiring compliance and audit trails

The two approaches are not mutually exclusive. Many teams use npx skills add for personal experimentation, then codify proven skills into apm.yml for team adoption.

APM vs manual skill management

Some teams manage skills by committing them directly to .claude/skills/ in version control. This provides reproducibility but becomes unwieldy as the skill count grows.

Drawbacks of manual management:

• No transitive dependencies: If a skill depends on another, you must manually track and update both.
• No integrity verification: You trust whatever is in git, with no hash-based verification.
• No policy enforcement: Every repository defines its own standards.

APM automates the tedious parts while preserving git as the source of truth for the manifest.

APM vs containerized agents

An alternative approach is to run agents inside containers with pre-installed skills. This works but introduces operational complexity—teams must manage container images, registry permissions, and updates.

APM + containers: The best of both worlds is to use APM inside containers. The Dockerfile becomes:

FROM node:20-slim
RUN curl -sSL https://aka.ms/apm-unix | sh
WORKDIR /workspace
COPY apm.yml apm.lock.yaml ./
RUN apm install --frozen-lockfile

This combines reproducibility (lockfile) with isolation (container), suitable for CI and production agent workloads.

Future roadmap and ecosystem trends

APM is evolving rapidly. Based on GitHub issues and community discussions (not official roadmap), likely future developments include:

Native support for skill versioning and semver

Currently, APM uses git tags (e.g., #v2.3.0) for versioning. The community has requested full semver support with version ranges:

dependencies:
  apm:
    - my-org/code-review: "^2.3.0"  # Any 2.x >= 2.3.0
    - my-org/security: "~1.5.0"     # 1.5.x only

This would enable automatic security updates within version constraints, reducing maintenance burden.

Integration with artifact registries

Large enterprises want to host APM packages in existing artifact registries (JFrog Artifactory, Azure Artifacts, AWS CodeArtifact). The registry protocol is designed for this, but tooling is still maturing.

Enhanced MCP server lifecycle management

Future versions may support MCP server health checks, automatic restarts, and distributed tracing, making MCP servers production-ready for mission-critical agent workloads.

Policy templates and compliance frameworks

The community is building policy templates for common compliance frameworks (SOC 2, HIPAA, PCI-DSS), allowing teams to adopt best practices without writing policies from scratch.

Bottom line

microsoft/apm is Microsoft's bet that agent configuration deserves the same tooling gravity as application dependencies: declarative manifests, lockfiles, policy, and multi-client install. If your team is outgrowing one-off npx skills add notes in Slack, APM is worth evaluating as repo-standard infrastructure—then prove it in CI with apm audit-style gates your security team can read.

For teams serious about agent-driven development, APM provides the reproducibility, governance, and security features needed to move from experimentation to production. The learning curve is minimal for anyone familiar with npm or pip, and the payoff—consistent agent behavior across teams and environments—is immediate.

Start small: migrate one shared skill to apm.yml, commit the lockfile, and validate that new team members can clone and install without manual steps. Once that works, expand to your full skill stack and introduce policy files for governance. The tooling is ready for production use, and the ecosystem is growing rapidly.

Product behaviors and client compatibility change by release; verify against microsoft.github.io/apm and the repository. ExplainX is not affiliated with Microsoft. Repository star and fork counts are approximate; check GitHub for current metrics.