apm-package-author

APM Package Author

APM (docs · GitHub) distributes GitHub Copilot skills, agents, and MCP servers as versioned packages installable with one command. Use this skill to create manifests, wire MCP dependencies, or troubleshoot installs.

When to Use

Use this skill when you need to:

• Create or update an apm.yml root manifest or packages/* sub-manifest for a GitHub Copilot skills/agents repository
• Bundle MCP server configuration into an APM package so consumers get MCP wired automatically on install
• Install a package from a GitHub repo using the APM CLI
• Troubleshoot APM install failures (missing .vscode/mcp.json, Codex CLI warnings, 404 errors, cached installs)

Do not use this skill for:

• General GitHub Copilot customization questions (use default agent)
• Creating SKILL.md files (use the skill-creator skill)
• Writing MCP server implementation code

Identify which task applies and jump to that section:

• Creating packages for a repo → Package Creation Workflow
• Installing a package into a project → Install Commands
• Something went wrong → Troubleshooting
• Detailed YAML reference → references/manifest-patterns.md
• MCP transport details → references/mcp-config.md

---

Package Creation Workflow

1. Install APM CLI (if not already installed)

curl -sSL https://aka.ms/apm-unix | sh   # macOS / Linux
irm https://aka.ms/apm-windows | iex     # Windows (PowerShell)

Verify: apm --version

2. Decide the package structure

Choose based on how consumers will install:

Pattern	When to use
Single-concern package packages/<topic>/apm.yml	One cohesive domain (e.g. terraform, diagramming, architect). Preferred.
Meta-package	One package references other packages — lets users apm install everything at once. Good for a repo root apm.yml.

For a typical skills repo, use one packages/<name>/ per domain plus a root apm.yml that pulls them all in. Read references/manifest-patterns.md for complete YAML examples of both patterns.

3. Scaffold each package directory

mkdir -p packages/<name>/.apm
touch packages/<name>/.apm/.gitkeep   # APM writes its install cache here — directory must exist

The .apm/.gitkeep placeholder is mandatory — without the directory APM may fail to write the install cache.

4. Write the apm.yml manifest

Minimum required fields:

name: my-package-name     # kebab-case, must be unique
version: 1.0.0
description: >
  One sentence describing what this bundle installs.
author: github-username
license: MIT
target: vscode            # always set for VS Code projects

dependencies:
  apm:
    - owner/repo/.github/agents/my-agent.agent.md
    - owner/repo/.github/skills/my-skill

Key rules:

• All apm: paths must be full owner/repo/... virtual paths — relative paths do not work.
• Exclude any skills marked 🚧 WIP. Comment them out with a reason so they're easy to re-add later: # cost-optimization excluded — WIP
• Agents can still be included even when their companion skills are WIP.
• target: vscode controls apm compile output format only — it does NOT suppress Codex CLI warnings about HTTP MCP servers (those are cosmetic; the install still succeeds).

If skills require MCP servers, add an mcp: block. Read references/mcp-config.md for transport types, Docker examples, and the Azure MCP exception.

5. Update the root apm.yml

Add the new package to the root manifest so apm install owner/repo installs everything:

dependencies:
  apm:
    - owner/repo/packages/my-new-package
    - owner/repo/packages/existing-package

6. Test the install

mkdir -p /tmp/apm-test/.vscode
cd /tmp/apm-test
apm install owner/repo/packages/<name>#your-branch --runtime vscode

Verify that .vscode/mcp.json was created (if the package has MCP deps) and that skills/agents landed in .github/. Then clean up:

rm -rf /tmp/apm-test

---

Install Commands

Standard install (VS Code project)

cd your-project
mkdir -p .vscode          # required if 'code' is not on your PATH
apm install owner/repo/packages/<name> --runtime vscode

--runtime vscode tells APM to write .vscode/mcp.json even if VS Code isn't detected. Without it APM looks for code on PATH or an existing .vscode/ directory — if neither exists, MCP config is silently skipped.

Install from a specific branch

apm install owner/repo/packages/<name>#branch-name --runtime vscode

Force re-fetch (bypass cache)

apm install owner/repo/packages/<name> --update --runtime vscode

Install everything from a repo

apm install owner/repo --runtime vscode   # uses root apm.yml

---

Troubleshooting

Symptom	Cause	Fix
.vscode/mcp.json not created	No .vscode/ dir and code not on PATH	mkdir -p .vscode then re-run, or add --runtime vscode
Codex CLI warnings about HTTP MCP servers	Codex is stdio-only; HTTP transports are incompatible with it	Cosmetic — install still succeeds. target: vscode does not suppress this.
404 / package not found	Wrong path or branch not pushed to remote	Check path matches directory name exactly; confirm branch is pushed
Stale / cached install	APM caches installs locally	Add --update to force re-fetch
apm compile output wrong format	Missing target: field	Add target: vscode to the manifest
Skills installed but not appearing in Copilot	.github/ location not registered in copilot-instructions.md	Ensure the project's copilot-instructions.md references the skills directory

---

New Package Checklist

• packages/<name>/apm.yml created with all required fields and target: vscode
• packages/<name>/.apm/.gitkeep created and committed
• All apm: deps use full owner/repo/... virtual paths
• WIP skills excluded and commented out with reason
• mcp: block added if any skills require MCP servers
• Root apm.yml updated to reference the new package
• Tested with --runtime vscode in a clean temp directory
• Branch pushed to remote before testing install