Create a package
Use this page when you have a skill, an instruction or an agent other teams keep
copying, and you want them to depend on it instead. By the end, a second
repository installs your package at v1.0.0 and records the exact commit in its
lockfile.
You need: APM (install it), and an
empty repository you can push to, cloned locally. This page calls it
you/my-skills; use your own owner and name.
-
Make the repository a package. From the root of your clone:
Terminal window apm init -yThis writes
apm.yml, the manifest. For an author it names the package (name,version,description,author) and lists its own dependencies. Leavetargets:commented out in a package you publish: a package’stargets:limits which harnesses its consumers get it for, so a Codex-only consumer would skip a package that declares Copilot and Claude Code. A harness is the agent tool that reads the files:.github/for GitHub Copilot,.claude/for Claude Code.includes: autolets APM install and pack everything you author under.apm/. -
Add a skill. A skill is a folder with a
SKILL.mdfile; the harness reads itsdescriptionand loads the skill when a request matches..apm/skills/review/SKILL.md ---name: reviewdescription: Review a diff against the team's checklist. Use when the user asks for a code review or says "review my changes".---# Review1. Check that every changed code path has a test.2. Flag names that do not say what the code does.3. List findings as Blocking, Should fix or Nit, with file and line.namemust match the folder name. Write skills, instructions and hooks covers every other kind of file. -
Install it into your own repository.
Terminal window apm install --target copilot,claude--targetpicks the harnesses for this run only, without writing them intoapm.yml.[i] Targets: claude, copilot (source: --target flag)[+] <project root> (local)|-- 1 skill(s) integrated -> .agents/skills/, .claude/skills/[i] Added apm_modules/ to .gitignore...[*] Updated local content in 0.6s.APM treats your own
.apm/folder as a package and writes the skill where each harness reads it:.agents/skills/for Copilot,.claude/skills/for Claude Code. Open either tool in this repository and try the skill before you ship it. -
Check the files before you release.
Terminal window apm audit[+] Replayed 1 package(s)[+] No drift detected[*] 2 file(s) scanned -- no issues foundapm auditcompares the deployed files with the lockfile and scans them for hidden Unicode characters, the kind that can carry instructions a reviewer cannot see. A finding here would also show up for every consumer. -
Commit, tag and push.
Terminal window git add apm.yml apm.lock.yaml .gitignore .apm/git commit -m "Add review skill"git tag -a v1.0.0 -m "v1.0.0"git push --follow-tagsThe tag is the release. Consumers resolve
v1.0.0to this commit. Keepversion:inapm.ymlequal to the tag; consumers see it in their lockfile. -
Install it from another repository. In a separate consumer repository that has an
apm.yml:Terminal window apm install you/my-skills#v1.0.0For a consumer that targets Copilot and Claude Code, the skill lands in
.agents/skills/review/and.claude/skills/review/. Itsapm.lock.yamlrecords the tag, the commit SHA and a SHA-256 hash for each file. -
List the versions you have published.
Terminal window apm view you/my-skills versionsAPM lists the repository’s tags and branches with their commits;
v1.0.0appears as a tag.
What a package holds
Section titled “What a package holds”APM reads primitives (its word for skills, instructions, agents, prompts, hooks
and the rest) from .apm/, one folder per kind:
- apm.yml name, version, targets, dependencies
- apm.lock.yaml
Directory.apm/
Directoryskills/
Directoryreview/
- SKILL.md
Directoryreferences/ optional files the skill loads
- …
Directoryinstructions/
- python.instructions.md
Directoryagents/
- reviewer.agent.md
Directoryprompts/
- release-notes.prompt.md
Directoryhooks/
- format-on-save.json
Commit apm.yml, apm.lock.yaml and .apm/. The deployed folders (.agents/,
.claude/, .github/) are output for your own use; consumers install from
.apm/, not from them.
Other package shapes
Section titled “Other package shapes”apm.yml with .apm/ is the recommended shape, because it carries version,
dependencies and every primitive kind. APM also installs repositories that have
no apm.yml:
- A skill repository:
SKILL.mdat the root, orskills/<name>/SKILL.mdfor several skills. - A plugin repository: a
plugin.jsonwithskills/,agents/andcommands/folders. See Build a plugin. - A single file: consumers can install one
.instructions.md,.prompt.mdor.agent.mdfrom your repository by its path.
Add apm.yml to any of these when your package needs its own dependencies.
Package types lists every layout and which one
wins when several are present.
Copyright (c) Microsoft Corporation. General documentation: CC-BY-4.0. Software, code examples and OpenAPM: Apache-2.0. See scope and exclusions.