Skip to content

richfrem/agent-plugins-skills / plugins/agent-extension-authoring/.apm/skills/packaging-with-apm

packaging-with-apm

Flagged

Packages, 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).

Packaging with APM (packaging-with-apm)

Packages agent extensions for APM without changing their source layout, installs them with backup and rollback, and publishes marketplace catalogs. Behaviour below was verified with APM 0.33.0.

Contents

Constraints

  1. Never change the source plugin to package it. Staging, manifests and bundles go under build/; APM does not need an apm.yml inside the plugin.
  2. Pin APM (apm-cli==0.33.0, see requirements-dev.in) and pin every install to #<tag> or #<commit-sha>.
  3. Compiled files are outputs. Never edit a generated AGENTS.md or GEMINI.md when .apm/ sources exist; change the source and recompile.
  4. No overwrites of an existing package directory without explicit confirmation.
  5. Never edit deployed files in harness folders; change the source and reinstall.

Modes

Pick the mode from the request, then read its reference before running anything.

ModeUse whenEntry pointReference
createNew APM-native package from scratchscripts/scaffold_apm.pycreate-apm-package.md
convertExisting plugin to APM, or an install checkscripts/apm_build_pipeline.pyconvert-plugin-to-apm.md
compileSingle-file context hosts (Codex, Gemini, OpenCode)apm compilecompile-apm-package.md
installInstall, update, roll back, removescripts/apm_consumer.pyinstall-apm-package.md
marketplaceMarketplace catalog and Gemini extensionscripts/audit_marketplace_sources.pymanage-marketplace.md

If the target harness supports native skill directories, prefer install over compile.

Quick start

Install the pinned APM CLI once (APM does not install skill dependencies):

python3 -m pip install -r requirements-dev.txt   # run in this skill folder; installs apm-cli==0.33.0
apm --version
python3 scripts/scaffold_apm.py --name <package-name>                       # create
python3 scripts/apm_build_pipeline.py --plugin plugins/<name> --apm <path>   # convert
python3 scripts/apm_consumer.py install --plugins <name> --ref <tag-or-sha> --global   # install

Workflow

  1. Choose the mode and read its reference (the pipeline findings and their standard fixes are in apm-alignment-fixes.md).
  2. Run the mode's entry point; dry-run first where the script offers it.
  3. Re-run until the mode's verification passes, then report the generated files or installed targets.
  4. On any failure follow that mode's section in fallback-tree.md.

materialize_copies.py and convert_symlinks_to_manifest.py stay in scripts/ while any plugin still uses a copy manifest; decouple_agent_paths.py rewrites hardcoded install-folder paths.

Verification

python3 scripts/validate_apm_package.py --path ./<package-name>   # create
apm compile --validate                                            # compile
python3 scripts/apm_consumer.py list-backups                      # install
python3 scripts/audit_marketplace_sources.py .                    # marketplace

Run the tests with python3 -m pytest tests (set APM_BIN to include the install and pack cases). Check the mode's section in acceptance-criteria.md.

References

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: 471kUpdated Claude CodeCodexUnverifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall