Install packages

To add an APM package to your project, declare it in apm.yml under dependencies.apm: and run apm install. APM resolves the graph, scans every primitive, writes apm.lock.yaml, and deploys the result into each agent harness directory you target.

apm install microsoft/apm-sample-package

That command edits apm.yml, fetches the package, walks its transitive deps, runs the security scan, writes the lockfile, and integrates skills, prompts, instructions, agents, hooks, and commands into every detected harness. The next contributor runs bare apm install and gets the same bytes, pinned by commit and content hash.

This page covers APM packages. For MCP servers, see Install MCP servers. For local bundles, see Deploy a bundle.

Add a dependency

Two ways. They produce the same apm.yml.

With the CLI. Pass the package as a positional argument. APM resolves it, validates it, and appends it to dependencies.apm: in apm.yml:

apm install microsoft/apm-sample-package#v1.0.0
apm install github/awesome-copilot/skills/review-and-refactor
apm install ./packages/my-shared-skills        # local path
apm install --dev acme/internal-debug-agents   # devDependencies

By editing apm.yml. Add entries under dependencies.apm: then run bare apm install:

name: my-project
version: 0.1.0
dependencies:
  apm:
    - microsoft/apm-sample-package#v1.0.0
    - github/awesome-copilot/skills/review-and-refactor
    - https://gitlab.com/acme/coding-standards.git
    - ./packages/my-shared-skills
devDependencies:
  apm:
    - acme/internal-debug-agents

apm install

Supported reference forms: owner/repo shorthand (with optional #ref for a tag, branch, or commit), full HTTPS or SSH git URLs, virtual subdirectory paths into a monorepo, single-file references, and local paths starting with ./, ../, or /. For private hosts and tokens, see Authentication.

What apm install does

The pipeline is deterministic. Each phase must pass before the next runs.

1. Resolve. Walk dependencies.apm: and devDependencies.apm:, follow transitive deps, pick versions.
2. Policy gate. If apm-policy.yml is in scope (locally or via your org), every resolved dependency is checked against the allow-list before anything touches disk. Skip with --no-policy for a single invocation; this does not bypass apm audit --ci.
3. Scan. The pre-deploy security scan inspects every primitive for hidden Unicode (zero-width characters, bidi controls, tag characters). Critical findings block the install. Override with --force.
4. Integrate. Write primitives into each selected target’s owned directories, such as .github/, .claude/, .grok/, and the cross-tool .agents/skills/.
5. Lockfile. Write apm.lock.yaml with pinned versions, content hashes, and the resolved dependency set.

For the deeper view of how compile fits in, see Lifecycle.

Coming from npm?

apm install mirrors npm install deliberately. The big difference: APM also runs a security scan and, if present, an org policy gate before writing anything to disk. To refresh dependencies to their latest matching versions or refs, use apm update (mirrors npm update). CLI upgrades use your package manager (brew upgrade apm for Homebrew), or apm self-update for standalone installs. See Update and refresh.

Where files land

APM detects which harnesses your project uses and deploys to all of them. Detection priority:

1. --target <slug> flag (highest).
2. The targets: field in apm.yml.
3. Auto-detect from the documented filesystem signals.

With no signal, install exits with a target-selection error.

Pin targets explicitly when you want reproducibility across machines:

name: my-project
targets:
  - copilot
  - claude
  - cursor

For the full reach map of which primitive lands where on each harness, see Primitives and targets.

Rule sync to Cursor (.cursor/rules/), Claude Code (.claude/rules/), Windsurf (.windsurf/rules/), and Kiro (.kiro/steering/) is automatic and idempotent – re-running apm install adopts unchanged rules without rewriting them.

What to commit

Commit apm.yml, apm.lock.yaml, and target-owned outputs; keep apm_modules/ gitignored. Committed agent files are reviewable and discoverable after clone, not necessarily self-contained: run apm install to restore linked package context. Keep those installed resources available while native agents or tools follow the deployed links; do not remove apm_modules/ just because install has finished.

See the Quickstart for details, and apm_modules/ is derived for reinstall and safe cleanup guidance.

Transitive dependencies and the lockfile

apm install resolves the full dependency graph, not just your top-level entries. Versions and content hashes are pinned in apm.lock.yaml so every contributor and CI run installs the exact same bytes. Commit the lockfile.

Lockfile replay

Plain apm install and apm install --frozen replay locked commits for unchanged dependencies, including transitive packages, and reuse matching cached package content when available. This keeps mutable branches and tags pinned to their recorded commits.

Run apm update or apm install --refresh to establish current upstream mutable refs. apm outdated checks the same current state without changing the lockfile. See the lockfile specification for the replay contract.

Transitive APM packages flow through automatically. Transitive MCP servers are gated: if a deep dependency declares a new MCP server, install pauses and asks you to re-declare it in your top-level apm.yml. Use --trust-transitive-mcp to skip this in trusted environments. See Drift and secure-by-default for the rationale.

Inspect what got installed

apm list                  # list scripts declared in apm.yml
apm view <package>        # details for one installed package

apm view reads from apm.lock.yaml and apm_modules/ – use it to confirm what shipped without re-running install. apm list shows the runnable scripts your manifest exposes (see Run scripts).

Useful flags

apm install --dry-run                  # resolve and print the plan; no writes
apm install --target claude,cursor     # only deploy to these harnesses
apm install --exclude gemini           # deploy to all targets except gemini
apm install --only apm                 # skip MCP server integration this run
apm install --frozen                   # CI: lockfile-only; fail on drift
apm install --update                   # resolve current upstream refs
apm install --refresh                  # resolve refs and bypass cached content
apm install --force                    # collision/security override; no ref refresh
apm install --dev                      # treat positional args as devDependencies
apm install -g <package>               # install to user scope (~/.apm/)
apm install -v                         # verbose: show resolution and integration

Targets with native user-scope instruction files pick up global instructions during install. Targets whose user-scope instruction surface is a root context file require explicit apm compile --global; apm install -g prints a hint and writes no root context file.

For project-scope installs, targets that require post-install instruction compilation print a hint when dependency instructions require apm compile. The hint names the root context files that compile will update.

For the full flag reference, run apm install --help or see CLI commands.

When things go wrong

• Symlink checkout fallback. If a checked-out file contains only a short relative path (for example ../shared/config.yml) instead of real content, Git substituted a plain-text fallback for a symlink it could not create. APM preserves Git’s detected core.symlinks setting instead of letting an inherited global value override it; this capability check is not Windows-specific, but Windows non-admin accounts are the common case without symlink-creation rights. Explicit command-scope Git settings still take precedence; APM does not change your global Git configuration. A successful checkout therefore does not guarantee that a package requiring real symlinks works – see “Skipped symlinked agent source” below for the related install-time check on agent sources. Use a package that ships real source files, or a symlink-capable environment.
• Critical security finding. Install aborts with the offending characters and file path. Patch upstream when you can; use --force only when you can document the exception.
• Policy violation. Install aborts before any file is written. Adjust the dependency or update org policy. See Governance on the consumer ramp.
• Auth failure on a private repo. Set GITHUB_APM_PAT or the matching host token. See Authentication and Private and org packages.
• Drift between apm_modules/ and the lockfile. Run apm audit --ci locally to reproduce the CI gate; see Update and refresh to recover.
• Skipped symlinked agent source. apm install warns and skips agent files or directories that are symlinks (for example .apm/agents -> ../agents). Fix by shipping real files and directories in the source package, then rerun apm install. Do not edit apm_modules/ – cached edits are not a durable fix. For a third-party package, ask the author to publish real sources. See Instructions and agents.

Once your dependencies are installed, scripts run them. Run scripts shows how to wire apm.yml’s scripts: block to invoke compiled prompts in any harness.