[FEATURE] Allow `install` to download and unpack a GitHub release automatically

[Werner-Swart-83]

Is your feature request related to a problem? Please describe.
We have a mono-repo were we are curating multiple skills, instructions and agents centrally, right now we don't have a lot of good options to version the packages. We either have to use poly-repos (which isn't great if you have to keep telling people where to find the skills, ect they are looking for) or use a repo wide version using a single tag (but this would not work if someone needs to use a previous version of one skill and then forced to use a newer version because of a another skill update they need), or we could use individual tags for each skill, instructions or agent (but this causes management overhead and teams would need to find the tag they are looking for.)

Describe the solution you'd like
We would like to pack and release each package in the mono repo individually in github, we would then like to use apm install {targeted-package-github-release} which should then download, unpack and install the agents.

Describe alternatives you've considered
We could still do this but then we would have to tell teams to first download the release and then unpack it...which seems reasonable...but we are getting push back because of it.

Additional context
None.

[danielmeppiel]

Hi @Werner-Swart-83 — thanks for the detailed framing of the monorepo pain. I want to address it head-on because I think APM already gives you what you need today, just through a different door than the one this issue proposes.

Quick recap of the tradeoffs you listed

1. Poly-repos — too much repo sprawl, hard to discover
2. Single repo-wide tag — can't pin one skill to v1.0 and another to v1.1
3. Per-skill prefixed tags — works for pinning, but creates "management overhead and teams would need to find the tag they are looking for"

The third option is the right primitive. The "find the tag" problem is exactly what marketplace.json is designed to solve — it acts as the discovery catalog so users never have to hunt for tags.

How to set it up today

Your monorepo at, say, acme/skills-monorepo with three packages:

acme/skills-monorepo/
├── packages/
│   ├── code-reviewer/      (.apm/, plugin.json)
│   ├── test-gen/           (.apm/, plugin.json)
│   └── docs-writer/        (.apm/, plugin.json)
└── .claude-plugin/
    └── marketplace.json

Each release of a package gets its own prefixed tag (code-reviewer-v1.2.3, test-gen-v0.5.0, etc.), then the marketplace.json pins each entry to its current ref + SHA using Anthropic's standard git-subdir source:

{
  "name": "acme-skills",
  "owner": { "name": "Acme" },
  "plugins": [
    {
      "name": "code-reviewer",
      "description": "AI-powered code review skill",
      "version": "1.2.3",
      "source": {
        "source": "git-subdir",
        "url": "https://github.com/acme/skills-monorepo.git",
        "path": "packages/code-reviewer",
        "ref": "code-reviewer-v1.2.3",
        "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
      }
    },
    {
      "name": "test-gen",
      "description": "Test scaffolding skill",
      "version": "0.5.0",
      "source": {
        "source": "git-subdir",
        "url": "https://github.com/acme/skills-monorepo.git",
        "path": "packages/test-gen",
        "ref": "test-gen-v0.5.0",
        "sha": "f9e8d7c6b5a49382716fedcba0987654321abcde"
      }
    }
  ]
}

Anthropic's git-subdir source is explicitly designed for monorepos and uses sparse partial-clone to only pull the requested subdirectory (spec reference). APM's resolver and downloader already handle this end-to-end — git-subdir is a first-class source type (marketplaces guide).

What your end users do

apm marketplace add acme/skills-monorepo     # registers the catalog
apm marketplace browse                       # lists all your skills with versions
apm install code-reviewer@acme-skills        # installs v1.2.3 (sparse-clones only packages/code-reviewer)
apm install test-gen@acme-skills             # installs v0.5.0

No tag hunting — apm marketplace browse shows them everything you've published. They install by name, not by tag.

What you (the maintainer) do for each release

1. Tag the new version: git tag code-reviewer-v1.3.0 && git push --tags
2. Update the code-reviewer entry in marketplace.json (bump ref + sha)
3. Commit, push — done. Users see the new version on apm marketplace update.

Step 2 is the friction you correctly identified ("management overhead"). For one-off releases it's a 30-second edit, but at scale it's tedious. That's exactly what #722 is being scoped to automate (apm marketplace generate — see thread there for design discussion). It's now on the roadmap.

About this issue specifically

The original ask — "let apm install download and unpack a GitHub Release" — conflates two things:

• Versioning semantics (per-package version pinning) → already solved via the pattern above, no new feature needed
• Transport (fetching a release tarball asset vs. sparse git clone) → orthogonal perf optimization, tactical

So I'd like to keep this issue open as the umbrella for the work that genuinely closes the gap:

1. A new "Distributing from a monorepo" docs guide with the pattern above + Release Please / changesets recipes — I'll open a PR shortly
2. [FEATURE] Add apm marketplace generate command to pack all plugins and produce a marketplace.json #722 (apm marketplace generate) for the authoring automation — promoted to roadmap

The PR you and @sergio-sisternes-epam have been iterating on (#677) overlaps with #722 in the right direction (the publish/validate pieces are valuable), but the versions[] array extends Anthropic's spec in a way I'd like to avoid — Anthropic is iterating that schema actively and divergence will bite us. I'll comment on the PR separately to discuss scope reduction.

Does the pattern above unblock you for now? Happy to walk through any edge cases you hit.