Manage dependencies

apm.yml is the manifest. apm.lock.yaml is generated by apm install. You can either edit apm.yml by hand and run apm install, or use apm install <pkg> to let the CLI append the entry for you. Either way the lockfile is a generated artifact — never hand-edit it.

edit apm.yml      ->  apm install   (manual: add or change a dep)
apm install <pkg> ->  (CLI mutates apm.yml + installs)
edit apm.yml      ->  apm prune     (remove a dep)

The dependencies block

APM dependencies live under dependencies.apm in apm.yml. The mapping shape is required — a flat list at the top level is rejected with an explicit error pointing you at the structured form.

name: my-project
version: 1.0.0

dependencies:
  apm:
    - microsoft/apm-sample-package#v1.0.0
    - github/awesome-copilot/skills/review-and-refactor

devDependencies has the exact same shape and is excluded from apm pack output. Use it for tooling and tests:

devDependencies:
  apm:
    - my-org/internal-test-skills

For the full manifest schema (every field, every type), see Package anatomy.

For MCP server entries (dependencies.mcp), see Install MCP servers.

Reference formats

Every entry under dependencies.apm is parsed by the same reference parser. The supported forms:

Form	Example	When to use
GitHub shorthand	owner/repo	Public GitHub repo, latest default branch.
Pinned ref	owner/repo#v1.0.0	Pin to a tag, branch, or full commit SHA.
Aliased	owner/repo@my-alias	Install under a custom directory name.
Pinned + aliased	owner/repo#v1.0.0@my-alias	Combine the two.
FQDN shorthand	gitlab.com/acme/repo#v2.0	Any git host, not just github.com.
Virtual subdirectory	owner/repo/skills/review	Install one skill folder from a monorepo.
Virtual file	owner/repo/prompts/review.prompt.md	Install a single primitive file.
HTTPS git URL	https://gitlab.com/acme/repo.git	Explicit URL, any host.
SSH SCP-style	git@gitlab.com:acme/repo.git	SSH with default port.
SSH protocol	ssh://git@gitlab.com/acme/repo.git	SSH with explicit scheme or port.
Local path	./packages/shared or /abs/path	Sibling package on disk.
Object form	{ git: <url>, path: <subpath>, ref: <ref> }	Escape hatch for nested groups, monorepo subpaths, or aliases that the string forms cannot express.

Object form in YAML:

dependencies:
  apm:
    - git: https://gitlab.com/acme/coding-standards.git
      path: instructions/security
      ref: v2.0
      alias: security

For private repos and non-GitHub hosts, see Private and org packages.

Add a dependency

You have two paths.

CLI shortcut. Run apm install <pkg>. The CLI appends the entry to dependencies.apm in apm.yml, then runs the full install pipeline. If the pipeline fails (policy block, download error), the manifest is atomically rolled back to its previous state.

apm install microsoft/apm-sample-package#v1.0.0

See Install packages for the canonical install flow and full flag list.

Manual edit. Edit apm.yml yourself, then run apm install with no arguments to sync.

apm install

The install command resolves the new entry, downloads it into apm_modules/, updates apm.lock.yaml with the resolved commit and content hash, and recompiles the deployed primitives for every target harness. Critical security findings block the install; pass --force only if you understand the risk. See Reference -> CLI commands for the full flag list.

Pin a version

Append #<ref> to a shorthand entry. <ref> can be a tag, branch, or full commit SHA:

dependencies:
  apm:
    - microsoft/apm-sample-package#v1.0.0       # tag
    - acme/playbooks#main                       # branch (moves)
    - acme/playbooks#a1b2c3d4e5f6...            # SHA (immutable)

Branches move; tags and SHAs do not. For reproducibility, prefer tags or SHAs. The lockfile pins the resolved commit either way, so two clones running apm install get the same bytes — but a branch ref will resolve to a new SHA on the next apm update.

Remove a dependency

1. Delete the entry from apm.yml.
2. Run apm prune.

apm prune --dry-run   # preview what gets deleted
apm prune             # delete orphaned packages from apm_modules/

apm prune removes any directory in apm_modules/ that no longer corresponds to a declared dependency. It does not touch your manifest, your lockfile entries are rewritten on the next apm install, and deployed files in .github/, .claude/, etc. are reconciled then too.

If you also want to refresh remaining deps to their latest refs, see Update and refresh.

The lockfile

apm.lock.yaml is generated by apm install. It records, for every dependency (direct and transitive):

• the resolved git commit SHA
• a SHA-256 content hash of the package
• the exact files deployed to your tree, with per-file hashes

Three rules:

1. Commit it. A teammate cloning the repo and running apm install gets byte-identical primitives only if the lockfile is in version control.
2. Do not hand-edit it. The file is regenerated on every install. Any manual change is overwritten or, for hash fields, will trip apm audit.
3. Inspect freely. It is plain YAML. Use it to answer “what version am I actually running?” without trusting the manifest, which may have floating refs.

For the full lockfile schema, see Package anatomy.

Coming from npm?

The split mirrors package.json + package-lock.json. The verbs match too: apm update refreshes dependencies to the latest matching refs (like npm update); apm install --frozen is the lockfile-only, fail-on-drift install for CI (like npm ci). To upgrade the apm CLI binary itself, use apm self-update.