Skip to content

Test a package locally

Use this page before you tag a release. You will install the package from your disk into a consumer repository, see your changes land on every apm install, and check the result the way a consumer would. The examples continue from Create a package: your package is ../my-skills, next to a scratch consumer repository.

In a scratch consumer repository with an apm.yml, install the package by path:

Terminal window
apm install ../my-skills
[+] ../my-skills
[*] Updated apm.yml with 1 new package(s)
...
[i] Targets: claude, copilot (source: apm.yml)
[+] ../my-skills (local)
|-- 1 skill(s) integrated -> .agents/skills/, .claude/skills/
...
[*] Installed 1 APM dependency in 0.4s.

APM copies the folder into apm_modules/_local/my-skills/ and deploys it like any other package. Edit a file in ../my-skills, run apm install in the consumer again, and the deployed copy changes. You do not need to commit or tag in between.

The consumer’s lockfile records source: local and the path. Keep this in a scratch repository: a teammate’s clone has no ../my-skills. Once you tag, replace the path with you/my-skills#v1.1.0.

Sometimes your package reaches the consumer through another package, so there is no line to change. A replace: rule in the consumer’s root apm.yml substitutes your local checkout, or a fork at a ref, everywhere that package appears:

apm.yml
$schema: https://microsoft.github.io/apm/specs/schemas/manifest-source-replacements-v1.schema.json
dependencies:
apm:
- contoso/review-skills#v1.0.0
replace:
- for:
git: https://github.com/contoso/review-skills.git
with:
path: ../my-skills

apm install prints [i] Replacement: contoso/review-skills#v1.0.0 -> ../my-skills and deploys your copy in place of the tag. For a fork, write with: {git: https://github.com/you/review-skills-fork.git, ref: my-fix}. Rules apply to direct and transitive dependencies. They belong in the consumer’s root apm.yml; rules declared inside a dependency do not redirect the consumer.

Keep maintainer dependencies out of your release

Section titled “Keep maintainer dependencies out of your release”

A package can depend on things its maintainers need and consumers do not, such as a test fixture package or a release checklist skill. Declare them as development dependencies:

Terminal window
apm install --dev owner/test-helpers
apm.yml
devDependencies:
apm:
- owner/test-helpers

apm install in your package repository deploys both dependencies and devDependencies. A consumer that installs your package resolves your dependencies and skips devDependencies, and apm pack leaves development dependencies out of plugin bundles.

A consumer who fixes a deployed file by hand can send you the fix. In their repository:

Terminal window
apm export-patch
[>] Replaying install (cache-only)...
[+] Replayed 2 package(s)
[i] .claude/skills/style-checker/SKILL.md -> microsoft/apm-sample-package:.apm/skills/style-checker/SKILL.md
[i] wrote /work/app/patches/microsoft__apm-sample-package@v1.0.0.patch
[*] Exported 1 edit(s) into 1 patch file(s) under /work/app/patches. Apply each with 'git apply' from the package repository root at the base noted in the patch header.

The patch maps the edited deployed file back to its source in your package:

patches/microsoft__apm-sample-package@v1.0.0.patch
# Exported by 'apm export-patch'
# package: microsoft/apm-sample-package
# source: microsoft/apm-sample-package
# base: commit fb2851683be0e0e7711421d518bd8dba23b0b1f6 (v1.0.0)
# Apply from the package repository root, checked out at the
# base above: git apply <this file>
--- a/.apm/skills/style-checker/SKILL.md
+++ b/.apm/skills/style-checker/SKILL.md
@@ -15,3 +15,4 @@
- Checks spacing values against the spacing scale
- Ensures typography follows the defined type scale
- Flags inconsistent naming conventions in CSS classes
+- Prefer small components.

Check out the base commit in your package repository and run git apply <file>. apm export-patch skips local-path packages: their source is already on disk.

In your package repository, run the same check consumers run:

Terminal window
apm install
apm audit

apm audit compares deployed files with the lockfile and scans them for hidden Unicode characters. To scan one file you are still writing, use apm audit --file .apm/skills/review/SKILL.md. Fix any finding before the tag: a consumer’s install blocks a critical finding in your package.

  • The consumer’s deployed files match your latest edit after apm install.
  • apm audit in your package repository prints No drift detected and no findings.
  • Every relative link in a deployed agent, instruction or prompt opens the file you meant.

Copyright (c) Microsoft Corporation. General documentation: CC-BY-4.0. Software, code examples and OpenAPM: Apache-2.0. See scope and exclusions.