richfrem/agent-plugins-skills / plugins/agent-extension-authoring/.apm/skills/packaging-with-apm
packaging-with-apm
FlaggedPackages, installs and distributes agent extensions with APM (Agent Package Manager). Use when the user wants to create a new APM package, convert or migrate an existing plugin to APM and check it installs cleanly, compile a package into AGENTS.md, CLAUDE.md or GEMINI.md, install, update, pin or roll back packages globally or per project, or create a plugin marketplace catalog (marketplace.json). Not for authoring a single skill, plugin, sub-agent or rule (use the authoring-* skills).
references/modes/install-apm-package.md
View on GitHub# Install APM Package (`install-apm-package`)
Installs APM packages, including this repository's plugins, globally or into a project, pinned to a ref, with backup and rollback of the global state. Behaviour below was verified with APM `0.33.0`.
## Contents
- [Critical Constraints](#critical-constraints)
- [Quick start](#quick-start)
- [Workflow](#workflow)
- [Where Files Land](#where-files-land)
- [Verification](#verification)
- [References](#references)
## Critical Constraints
1. **Pin every install** to `#<tag>` or `#<commit-sha>`. `scripts/apm_consumer.py` refuses unpinned installs.
2. **Never edit deployed files** in harness folders; change the source package and reinstall.
3. **Commit `apm.yml` and `apm.lock.yaml` together** for project installs; use `apm install --frozen` in CI.
4. **One installer per plugin**: do not install the same plugin with APM and the legacy `plugin-add` installer (duplicate skill names).
5. **Scope Discipline (Global vs. Local)**:
- **Global (`--global`)**: Install only universal developer and agent OS infrastructure (`agent-plugins-skills`). Never install domain-specific plugins globally, or non-domain projects will suffer context window pollution and false-positive tool routing.
- **Project-Local**: Install domain-specific packages (e.g. `@sharepoint/sharepoint-workbench`) locally inside the specific consuming project via `apm.yml`.
6. **APM CLI Absolute Path Invariant**: When installing local directory packages globally (`--global`), APM `0.33.0` rejects relative paths (e.g., `./plugins/...`). Always supply the full absolute filesystem path.
7. **Consuming Project Git Hygiene**: Projects using local APM installs must exclude deployed harness folders in `.gitignore` (`.agents/`, `.claude/skills/`, `.codex/`, `.github/agents/`, `apm_modules/`).
## Quick start
```bash
python3 scripts/apm_consumer.py install --plugins dev-utils --ref <tag-or-sha> --global
```
Default targets are `claude,copilot,agy,codex`. Add `--skill <name>` (repeatable, one plugin) to install only some skills.
## Workflow
1. **Preview**: `apm install <package>#<ref> --target claude --dry-run`.
2. **Install**: `scripts/apm_consumer.py install ...` (global installs back up `~/.apm/apm.yml` and `apm.lock.yaml` first), or `apm install <package>#<ref> --target <targets>` in a project.
3. **Move to a new release**: `scripts/apm_consumer.py set-ref --ref <new-ref>` rewrites every global install from this repository and reinstalls (after a backup).
4. **Roll back**: `scripts/apm_consumer.py rollback [--backup <id>]` uninstalls packages added since the backup, restores both files, and reinstalls. Restoring the files alone would leave orphaned skills.
5. **Remove**: `apm uninstall <package> [--global]`. It keeps untracked files and stops (keeping its records) if a user file sits inside a package's skill folder.
## Where Files Land
| | Project install | Global install |
|---|---|---|
| Skills | `.claude/skills/`; `.agents/skills/` (copilot, codex, agy) | `~/.claude/skills/`; `~/.agents/skills/`; `~/.gemini/antigravity-cli/skills/` |
| Agents | `.claude/agents/`, `.github/agents/`, `.codex/agents/` | `~/.claude/agents/`, `~/.copilot/agents/`, `~/.codex/agents/` |
| Manifest, lockfile, cache | `apm.yml`, `apm.lock.yaml`, `apm_modules/` | `~/.apm/` (Windows: `%USERPROFILE%\.apm\`) |
A global install writes nothing into any repository; every repository uses the same user-level copies. Global installs give agy no hooks or agents. Plugins whose shared files come from a copy manifest are installed from their packed bundle (`apm install <bundle>.zip`), not the raw git path.
## Verification
```bash
apm install --frozen # project: reproduce exactly from the lockfile
python3 scripts/apm_consumer.py list-backups
```
In Claude Code the installed skills appear in the skills list; in Copilot CLI use `/skills list`. Tests: `tests/test_apm_consumer.py` in this skill.
## References
- [legacy-plugin-conversion-guide.md](../legacy-plugin-conversion-guide.md) — End-to-end migration guide covering scope discipline, git hygiene, and consumer refactoring.
- [acceptance-criteria.md](../acceptance-criteria.md) — Acceptance gates and target verification criteria.
- [fallback-tree.md](../fallback-tree.md) — Fallback resolution for installation failures and target collisions.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |