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/apm-alignment-fixes.md

View on GitHub
# APM Alignment: Standard Fixes

Every finding from `scripts/apm_build_pipeline.py` carries a `fix` id from this table. The same
misalignment with the APM model is always fixed the same way. The pipeline never edits the source
tree: it reports the fix (and, for SF-3, the exact replacement link), and the fix is applied as a
normal reviewed source change.

Direction for every fix: the APM migration plan (`docs/plans/apm_migration_plan.md` in the
source repository), Section 10.3. Each file lives in one canonical place; skills cite it with a relative markdown link;
no new symlinks and no duplicate copies.

| Fix | Finding(s) | Standard fix |
| :--- | :--- | :--- |
| **SF-1** | `broken_symlink` | The symlink points at a file that moved or no longer exists. Delete the dummy symlink file. If anything cites it, point that citation at the canonical file with a relative link. Remove its entry from `symlinks.json` if it has one. Do not repoint the symlink and do not copy the file in. |
| **SF-2** | `cross_plugin_symlink` | The symlink pulls a file from another plugin, which APM rejects (a link outside the package aborts the install) and ADR-001 forbids. Delete the symlink and its `symlinks.json` entry. Where the content is needed, reference the other plugin's skill or rule by name instead of copying it. |
| **SF-3** | `broken_relative_link`, `link_escapes_package` | APM copies only the skill folder, but rewrites **markdown links** that leave it to point into its package cache (`apm_modules/` in a project, `~/.apm/apm_modules/` globally), so links to sibling skills and plugin-root files work for every target and scope. Fix broken links so they resolve to a file inside the plugin. A link that leaves the plugin is not rewritten and breaks: reference the other plugin's skill by name instead. |
| **SF-4** | `symlink_in_package`, `sha256_mismatch` | Staging did not dereference a link. Re-run the pipeline. If it persists, the link is not tracked in git (normalize reads links from the git index); commit it or remove it. |
| **SF-5** | `frontmatter_name`, `frontmatter_description` | Set the `SKILL.md` frontmatter `name` to the skill folder name, and give it a third-person `description`. |
| **SF-6** | `skill_not_deployed`, `deployed_content_mismatch`, `uninstall_left_files` | Compare the staged package with the fixture install in `build/test-deploy/<plugin>/`. A skill without a valid `SKILL.md` is not deployed. If deployed content differs and its links do not resolve, record it as an APM issue. |
| **SF-7** | `apm_install_failed` | Read the APM error in the report's `test_deploy.steps`. Known case: the CLI accepts the target `agents`, but a package `apm.yml` accepts only `agent-skills`; the package stage maps it automatically. |
| **SF-8** | `path_not_rewritten` | APM rewrites only markdown links. Paths in inline code, code blocks or plain text that climb out of the skill folder (e.g. `python3 ../../scripts/x.py`) break after install. For documents, use a markdown link. For a script the skill tells the agent to run, keep the script inside that skill (`scripts/x.py`). |
| **SF-9** | `rules_not_deployed` (info) | APM does not install a plugin's `rules/` folder. Decision (2026-10-22): rules stay outside APM; setup copies the rules a project needs into `.agent/rules/`, and `AGENTS.md` lists them there. No change to the package. |
| **SF-10** | `lsp_config_invalid` | APM reads `lsp.json` as a flat map of server name to `{command, ...}`. A file shaped `{"languageServers": {}}` declares no servers and APM skips it with a warning: delete the empty file, or rewrite it in the flat format if servers are needed. |
| **SF-11** | `hook_script_harness_path` | Hook scripts run under every target harness (APM copies them into `.claude/hooks/`, `.agents/hooks/`, `.codex/hooks/`, `.github/hooks/scripts/`). A script that reads or writes `.claude/...` or `.agents/...` assumes one harness. Use `Path(__file__)` for the script's own files and a harness-neutral project path (e.g. `context/`) for state. |
| **SF-12** | `agent_mirrors_skill` | An `agents/<name>.md` file that is a symlink (or copy) of a skill's `SKILL.md` carries links written relative to the skill folder, which break once the file sits in `agents/` (and in each harness's agents folder after install). Write the agent as its own short definition that uses the skill by name. Changes agent behaviour, so review before applying. |
| none | `link_rewritten_by_apm` | Informational. APM rewrites cross-skill links in deployed markdown to point into `apm_modules/`, and they still resolve. |

## Examples already applied

- **SF-1**: six dangling links in `plugins/agent-extension-authoring/references/ADRs/` pointed at a root
  `ADRs/` folder that moved to `docs/ADRs/`. The dummy files were deleted; nothing cited them by path.
- **SF-2**: `plugins/agent-extension-authoring/skills/audit-plugin/references/destructive-action-guard.md`
  linked into `plugins/agent-agentic-os/rules/`. The symlink and its `symlinks.json` entry were removed.
- **SF-3**: `plugins/agent-extension-authoring/references/index.md` (deployed through
  `ecosystem-authoritative-sources` as a symlink) linked to a sibling that only exists next to the
  plugin-root original, so the link did not resolve from the skill. It now points at
  `../../create-skill/references/anthropic-skill-authoring-best-practices.md`.
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 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