Replace legacy metadata guidance with extensions

[jonathanhefner]

ADR-0017 replaced the native metadata member, but the authoring guides and Claude marketplace mapping still showed documents that conflict with the normative CDDL.

This PR documents extensions at the catalog, entry, and Trust Manifest scopes, and describes the official metadata extension (without imposing a second namespace convention on its schemaless payload).

This PR also omits selective Claude description and homepage mappings, and removes the obsolete Adspirer marketplace snapshot.

Closes #103.

[darrelmiller]

While you're touching the Claude mapping, docs/mappings/claude-code-plugins.md still has two \sha1:\ sourceDigest values (lines 113 and 133) that violate the spec's Digest Format rules (SHA-256 or stronger required). These are git commit SHAs, not content digests — PR #81 originally fixed them in the appendix but the mappings were extracted before that landed.

Could you also fix these while you're in here? The Adspirer entry you're already removing has one; the Aikido entry at line ~128 has the other. The git SHA should either move to an extension (e.g. \com.github.sourceSha) or just be dropped from \sourceDigest.

[Tehsmash]

The extensions change LGTM. I hadn't realised that we had metadata/extensions on the top level catalog object until I re-read this.

Main issue I have is on the claude code market place conversion stuff, after walking through the examples it seems like we have a bit of a weird situation with the URL and types which needs a bit more discussion IMO.

[Tehsmash]

I thought this section was to show a conversion from marketplace.json to an ai-catalog.json. The new text doesn't make as much sense I think. Perhaps something like:

A marketplace.json containing one plugin "agent-sdk-dev" maps to an AI catalog as follows:

This makes me wonder if we can create a tool to do this conversion automatically :/

[jonathanhefner]

I think the underlying problem is that https://github.com/anthropics/claude-plugins-official/blob/main/.claude-plugin/marketplace.json is not a good basis for an example. It is large and sprawling, and has already drifted from the excerpt we previously had.

I added a commit to replace it with a synthetic example.

[Tehsmash]

I understand the reason for not using sourceDigest here as its suppose to be a sha256 content digest of the artifact but having an artifact sourced directly from from a git repo is becoming more and more common.

I'm thinking that we probably need to encode this information in the "version" or "URL" field:

"source": {
        "source": "git-subdir",
        "url": "https://github.com/adobe/skills.git",
        "path": "plugins/creative-cloud/adobe-for-creativity",
        "ref": "main",
        "sha": "1307e2c03b9cd20c49872be8cbdfda7ee9aa8c7e"
      },

There is a problem with "version" as the plugin.json itself has a version which is not the "sha" and they should probably match. So then I would suggest that we just encode it in the URL itself for example something like:

https://github.com/adobe/skills.git/plugins/creative-cloud/adobe-for-creativity@1307e2c03b9cd20c49872be8cbdfda7ee9aa8c7e

What I find a little bit odd about this whole conversion is that the "type" is "application/vnd.anthropic.claude-plugin+json" however the given URL's do not resolve to the plugin.json. The "correct" URL for that would be something like:

https://raw.githubusercontent.com/adobe/skills/refs/heads/main/plugins/creative-cloud/adobe-for-creativity/.claude-plugin/plugin.json

But resolving the plugin.json directly isn't useful as it doesn't come with any information about where to find the plugin "code".

There is also an open question of "how do I know that the URL is a git URL?"

I think in reality we're actually defining here is something like application/vnd.anthropic.claude-plugin+git here which implies that you should treat the URL as a git repo which resolves to a plugin folder not a JSON document.

This would then allow you to also have application/vnd.anthropic.claude-plugin+zip or whatever which could be a different packaging mechanism.

[jonathanhefner]

This led down a rabbit hole. I added a commit to try to address some of the concerns, but if we want to work on this further I would strongly suggest a separate PR.

If desired, I can separate commits 928e437 and a5fcfd6 out of this PR so that it only contains commit 3596257.

[Tehsmash]

It really is a rabbit hole, thanks for trying to resolve it!

3596257 is way better already, but my main issue is that pointing to plugin.json isn't "useful" for a claude plugin, it'll get you the metadata for the plugin but that doesn't include any reference to the actual plugin code.

One option based on https://code.claude.com/docs/en/plugin-marketplaces#plugin-sources is to add different types like:

application/vnd.anthropic.claude-plugin+git
application/vnd.anthropic.claude-plugin+npm
application/vnd.anthropic.claude-plugin+zip

For each of these the catalog entry URL can have a different semantic meaning e.g. +git its a git file distribution, +zip its a zip file. +npm its the NPM package identifier. This is in alignment with how we're doing agent skills.

Alternatively, I think we perhaps need to go up a level and introduce a "plugin card" (sick emoji) which literally just encodes https://code.claude.com/docs/en/plugin-marketplaces#plugin-entries as a separate thing.
You could quite cleanly embed this into AI Catalog something like:

{
   "entries": [
       {
         "type": "application/vnd.anthropic.claude-plugin-entry+json",  <--- note not plugin.json but plugin-entry.json
         "data": {
            {
			      "name": "code-formatter",
			      "source": {
			        "source": "github",
			        "repo": "company/deploy-plugin"
			      },
			      "description": "Automatic code formatting on save",
			      "version": "2.1.0",
			      "author": {
			        "name": "DevTools Team"
			      }
			},
         }
       }  
   ] 
}

This pushes all the "sources" stuff out of AI Catalog making it a claude specific thing to deal with. The "plugin entry" schema is closer aligned with something like an MCP server card or A2A card.