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

FileKindSize
SKILL.mdskill md5.3 KB
evals/evals.jsonconfig2.7 KB
examples/marketplace.jsonconfig45 B
references/acceptance-criteria.mdmarkdown4.6 KB
references/agent-package-manager-overview.mdmarkdown28.7 KB
references/apm-alignment-fixes.mdmarkdown5.3 KB
references/diagrams/packaging-with-apm-flow.mmdother590 B
references/fallback-tree.mdmarkdown1.8 KB
references/legacy-plugin-conversion-guide.mdmarkdown15.4 KB
references/marketplace-architecture.mdmarkdown1.5 KB
references/marketplace-schema.mdmarkdown2.5 KB
references/marketplace.mdmarkdown11.5 KB
references/modes/compile-apm-package.mdmarkdown1.7 KB
references/modes/convert-plugin-to-apm.mdmarkdown7.3 KB
references/modes/create-apm-package.mdmarkdown1.7 KB
references/modes/install-apm-package.mdmarkdown4.3 KB
references/modes/manage-marketplace.mdmarkdown2.1 KB
requirements-dev.inother657 B
requirements-dev.txtmarkdown3.3 KB
requirements.inother148 B
requirements.txtmanifest171 B
scripts/apm_build_pipeline.pyscript35.1 KB
scripts/apm_consumer.pyscript11.3 KB
scripts/apply_symlink_repairs.pyscript1.7 KB
scripts/apply_symlink_repairs.shscript40 B
scripts/audit_marketplace_sources.pyscript2.5 KB
scripts/check_for_broken_symlinks.pyexecutablescript6.6 KB
scripts/convert_symlinks_to_manifest.pyscript6.7 KB
scripts/decouple_agent_paths.pyscript9.1 KB
scripts/fix_inside_plugin_symlinks.pyscript11.3 KB
scripts/materialize_copies.pyscript5.3 KB
scripts/migrate_to_apm.pyscript16.4 KB
scripts/scaffold_apm.pyscript8.6 KB
scripts/validate_apm_package.pyscript5.7 KB
tests/test_apm_build_pipeline.pyscript10.2 KB
tests/test_apm_consumer.pyscript4.8 KB
tests/test_audit_decoupled_state.pyscript8.6 KB
tests/test_convert_symlinks_to_manifest.pyscript5.3 KB
tests/test_decouple_agent_paths.pyscript4.8 KB
tests/test_scaffold_apm.pyscript1.7 KB

references/acceptance-criteria.md

View on GitHub
# Acceptance Criteria: packaging-with-apm

Merged verbatim from the five retired APM skills; one section per mode.

## Mode: create-apm-package

- [ ] Successfully validates that the package name is kebab-case.
- [ ] Refuses to scaffold into an existing plugin directory (unless `--allow-hybrid` is set).
- [ ] Creates a valid `apm.yml` with metadata and governance lane.
- [ ] Creates the full `.apm/` source tree for primitives.
- [ ] Creates `docs/governance.md` matching the selected lane.
- [ ] Creates a boilerplate `README.md` and `.gitignore`.
- [ ] Runs `validate_apm_package.py` and reports results.
- [ ] Handles `--dry-run` without making any filesystem changes.
- [ ] Provides a clear "Next Steps" summary for the user.

## Mode: convert-plugin-to-apm

- [ ] Correctly identifies the source plugin by looking for `.claude-plugin/plugin.json`.
- [ ] Defaults to **Overlay mode** to prevent primitive movement.
- [ ] In **Overlay mode**, adds `apm.yml` and `docs/governance.md` without moving files.
- [ ] In **Full mode**, creates a new directory and migrates all primitives to `.apm/`.
- [ ] Correctly maps `commands/` to `.apm/prompts/`.
- [ ] Preserves existing plugin primitives untouched in overlay and hybrid modes; only APM overlay files are added.
- [ ] Generates a `docs/governance.md` file matching the selected lane.
- [ ] Runs `validate_apm_package.py` on the result.
- [ ] Flags "Dual Manifest" risk if both `plugin.json` and `apm.yml` exist without hybrid documentation.
- [ ] Handles `--dry-run` without making any filesystem changes.

## Mode: compile-apm-package

- [ ] Explained the difference between `install` and `compile` to the user.
- [ ] Verified package integrity before execution.
- [ ] Correctly identified that the target harness requires a top-level context file.
- [ ] Executed `apm compile` successfully.
- [ ] Verified the presence of generated artifacts (AGENTS.md, GEMINI.md, etc.).
- [ ] Warned the user that compiled files are not the canonical source of truth.

## Mode: install-apm-package

- [ ] Verified `apm.yml` presence before proceeding.
- [ ] Successfully executed `validate_apm_package.py` with 0 errors.
- [ ] Correctly auto-detected the harness target or exited with code 2 if ambiguous.
- [ ] Verified converged skill materialization into `.agents/skills/<package-name>/` by default.
- [ ] Supported `--target agent-skills` and `--target all,agent-skills` combinations.
- [ ] Supported `--legacy-skill-paths` for per-client skill deployment.
- [ ] Executed `apm install --dry-run` for preview when requested.
- [ ] Verified that `apm.lock.yaml` was updated or already present.
- [ ] Reminded the user of the "Source in .apm/" rule after materialization.
- [ ] Explains that `all,agent-skills` is a broad routing test, not always the recommended runtime install.
- [ ] Warns that installing both `.agents/skills/` and target-specific skill folders can cause duplicate skill discovery.
- [ ] Recommends the smallest target set needed for the user’s active runtime.
- [ ] Distinguishes install verification from runtime-discovery hygiene.

## Mode: manage-marketplace

To verify the skill correctly guides the user in setting up and managing a marketplace.

| Scenario | Expected Result | Pass/Fail |
|----------|-----------------|-----------|
| **Setup location** | The guide directs the user to place `marketplace.json` inside a `.claude-plugin/` directory at root. | **PASS** |
| **Owner field** | The `owner` field is created and defined as an object: `{"name": "Owner Name"}`. | **PASS** |
| **Name Field** | The `name` field strictly uses **kebab-case** validation. | **PASS** |
| **CLI Directives** | The guide references addition using `/plugin marketplace add` TUI behavior directives. | **PASS** |
| **Variables mapping** | The guide lists `${CLAUDE_PLUGIN_ROOT}` and `${CLAUDE_PLUGIN_DATA}` absolute references mapped safely for author hooks. | **PASS** |

## Failure Patterns (FAIL)

| Scenario | Incorrect Result |
|----------|-----------------|
| **Wrong file location** | Agent places `marketplace.json` at the repo root without a `.claude-plugin/` parent directory. |
| **String `owner` field** | Generated catalog uses `"owner": "Acme Corp"` instead of `"owner": {"name": "Acme Corp"}`. |
| **Non-kebab-case name** | Generated catalog uses names with spaces or mixed case (e.g., `"My Plugin"` or `"MyPlugin"`). |
| **Wrong CLI command** | Skill tells consumers to run `claude plugins add-marketplace` or any other non-canonical command. |
| **Hardcoded paths in hooks** | Plugin author guidance uses absolute host paths (e.g., `/home/user/.claude/plugins/my-plugin/run.sh`) instead of `${CLAUDE_PLUGIN_ROOT}`. |
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: 472kUpdated Claude CodeCodexVerifiedInstall
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