@SebastienDegodez — thank you for this. The plugin marketplace ecosystem is an industry standard now and APM needs to support it. This review is about routing it through APM's existing architecture, not building alongside it.

Decision: Request changes

APM's detection pattern (how it works today)

APM already handles five foreign formats, all the same way:

apm install owner/repo
        ↓
   clone to apm_modules/
        ↓
   look at what's inside:
     ├─ apm.yml only           → APM_PACKAGE
     ├─ SKILL.md only          → CLAUDE_SKILL (synthesize apm.yml)
     ├─ apm.yml + SKILL.md     → HYBRID
     ├─ .collection.yml        → COLLECTION (download items, generate .apm/)
     └─ single .prompt.md file → VIRTUAL_FILE (wrap in package)

No flags. No separate commands. apm install figures it out. The user never needs to know or care what format the source uses.

What plugin support should look like

The same pattern, extended:

apm install anthropics/claude-code-plugins/commit-commands
        ↓
   clone to apm_modules/
        ↓
   look at what's inside:
     ├─ apm.yml       → APM_PACKAGE (existing)
     ├─ SKILL.md      → CLAUDE_SKILL (existing)
     ├─ plugin.json   → MARKETPLACE_PLUGIN ← new detection
     └─ ...

When the downloader finds plugin.json (and no apm.yml), it does what it already does for SKILL.md:

1. Parse plugin.json for metadata (name, description, version)
2. Map the plugin's agents/, skills/, commands/ into .apm/ subdirectories
3. Synthesize apm.yml
4. Set PackageType.MARKETPLACE_PLUGIN
5. From here on it's a normal dependency — lock file, version pinning, transitive resolution, conflict detection, everything works

The user experience is just:

apm install anthropics/claude-code-plugins/commit-commands

Or in apm.yml:

dependencies:
  apm:
    - company/coding-standards#v2.0
    - anthropics/claude-code-plugins/commit-commands#v1.2.0

That's it. No apm plugin subcommand. No plugins: section. No @claude syntax. Just apm install, same as everything else.

The marketplace discovery question

The useful part of your PR — MarketplaceManager resolving marketplace.json manifests — answers a real question: "How do I find the repo URL for a plugin I saw in the Claude marketplace?"

But that's a browsing concern, not an install concern. Once a user knows the repo, it's just apm install owner/repo/plugin-name. The mapping from marketplace name to repo URL is what the marketplace UI already does (ClaudePluginHub, /plugin in Claude Code, etc.).

If we want APM to help with discovery later, it can be a lightweight convenience:

apm browse claude    # opens marketplace URL in browser

But that's a separate, smaller feature — not a prerequisite for plugin support.

What to keep from your PR

Implementation plan

Phase 1 — plugin.json as detected format (core value, small surface area)

1. Add MARKETPLACE_PLUGIN to PackageType enum
2. Write plugin_parser.py in src/apm_cli/deps/ — parses plugin.json, maps agents/skills/commands to .apm/ structure, synthesizes apm.yml
3. Extend GitHubPackageDownloader detection: after checking for apm.yml and SKILL.md, check for plugin.json
4. Extend validate_virtual_package_exists() to check for plugin.json in subdirectory packages
5. scan_dependency_primitives() already handles the rest — no changes needed

Result: apm install owner/repo works for plugin repos. Lock file, version pinning, transitive deps, conflict detection — all free.

Phase 2 — Marketplace source resolution (optional, later)

Your MarketplaceManager code becomes a convenience layer that maps short names to repo URLs. Could be a standalone apm browse or a resolver that feeds into apm install. This is additive and doesn't block Phase 1.

Why this matters architecturally

APM currently has one install pipeline, one manifest format, one discovery system, one lock file. Every foreign format normalizes into that single model. This is the project's most important architectural invariant — it's what makes APM "the npm for agent primitives" rather than "a wrapper around five different tools."

PR #83 as written breaks that invariant by creating a parallel pipeline. The plugin ecosystem deserves full support — but through the existing architecture, not alongside it.

Your plugin.json parsing code and test fixtures are genuinely useful. I'd welcome a V2 that integrates them as a format adapter in the existing pipeline. Happy to pair on scoping that.

Hello @danielmeppiel , sorry I'm in holidays.

Can you take this Pull Request or you can wait one moment ?

@danielmeppiel Phase 1: Done

test

Hey @SebastienDegodez, thanks for pushing this forward — the normalization approach (plugin → apm.yml + .apm/) is exactly the right direction, and the test structure shows good discipline.

I tested against real-world plugin repos and cross-referenced with the official spec (plugin reference, marketplace spec), and the implementation needs to be re-grounded.

The key insight from the spec:

"The manifest is optional. If omitted, Claude Code auto-discovers components in default locations and derives the plugin name from the directory name."

A Claude plugin has no mandatory files. .claude-plugin/plugin.json is optional, and when present, only name is required. version and description are optional metadata. author is an object {name, email, url}, not a string.

This means the normalization should not gate on finding plugin.json. Instead, it should be the fallback when no apm.yml or SKILL.md exists:

apm.yml found?   → APM package (existing)
SKILL.md found?  → Claude skill (existing)
Neither?         → Normalize as Claude plugin (new)

What "normalize as Claude plugin" means:

1. If .claude-plugin/plugin.json exists, read metadata from it (only name guaranteed; derive from dir name if absent)
2. Auto-discover standard component directories per the spec: agents/, commands/, skills/, hooks/, .mcp.json, .lsp.json, settings.json
3. Generate apm.yml + .apm/ from what's discovered
4. Copy .mcp.json through (MCP-based plugins like github, playwright, slack need it to function)

Specific issues in the current implementation:

1. parse_plugin_manifest() requires version + description — crashes on every real Anthropic plugin (none have version)
2. find_plugin_json() is the gate for detection — should be optional metadata lookup, not a required step
3. author handled as string in fixtures — spec defines it as object {name, email, url}
4. .mcp.json not carried through — external plugins are MCP wrappers and would be non-functional
5. MarketplaceEntry model / scan_plugin_primitives() — Phase 2+ material, remove from this PR

Acceptance bar:

apm install owner/repo (and apm install owner/repo/path) should work for any directory that follows the Claude plugin spec — including one with no plugin.json at all, just standard component directories. Test it against real plugins from anthropics/claude-plugins-official (e.g., plugins/pr-review-toolkit, plugins/hookify, external_plugins/github).

You're on the right track with the normalization architecture. The main shift is treating plugin normalization as the fallback path (not a detected path), and aligning the parser with the spec's permissiveness. Happy to pair on any of this.

Should consider testing apm driven plugin installation in a way that the plugins installed with APM are immediately picked up by VSCode / GitHub Copilot - https://github.com/microsoft/vscode-docs/blob/vnext/docs/copilot/customization/agent-plugins.md

@microsoft-github-policy-service agree