thomast1906/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