[FEATURE] Support skills-only Agent Plugins 1.0.0 packages

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Agent Plugins 1.0.0 defines a published portable package contract: a root plugin.json, a required canonical $schema, fixed immediate-child skill discovery under skills/, and specified validation, containment, and failure behavior.

Claude Code 2.1.240 has partial format compatibility. It accepts a root plugin.json through its existing native plugin handling, so a skills-only package can appear to work. However, the validator does not select Agent Plugins rules from $schema.

Starting from a valid Agent Plugins 1.0.0 manifest, both of these pass claude plugin validate --strict:

jq 'del(.["$schema"])' plugin.json > without-schema.json
claude plugin validate --strict without-schema.json

jq '.["$schema"] = "https://agent-plugins.org/schemas/999.0.0/plugin.schema.json"' plugin.json > unsupported-schema.json
claude plugin validate --strict unsupported-schema.json

Both print:

✔ Validation passed

The published specification requires clients to select locally supported rules from the canonical schema identifier, reject unsupported versions, enforce package-root containment, discover skills from the fixed location, and isolate invalid components without disabling valid siblings.

Right now, a valid 1.0.0 package, a manifest with no portable schema, and a manifest claiming an unsupported Agent Plugins version are indistinguishable to the strict validator. Plugin authors must either maintain duplicate client packaging or rely on incidental overlap without Claude Code enforcing the portable contract the package declares.

Proposed Solution

When a root plugin.json declares the canonical Agent Plugins 1.0.0 schema identifier, load the directory as an Agent Plugins package and implement skills-only client conformance.

For the first increment:

1. Recognize https://agent-plugins.org/schemas/1.0.0/plugin.schema.json locally without retrieving the schema while loading a plugin. Reject unsupported Agent Plugins versions with a specific diagnostic.
2. Apply the manifest validation and failure rules from sections 5, 8, and 11. Unknown top-level fields and a non-object extensions field are reported and ignored. Other schema violations are fatal and prevent component discovery.
3. Treat root plugin.json as the sole source of portable core metadata. No native or client-specific manifest may replace, supplement, or override its core fields.
4. Ignore unimplemented extensions namespaces without validating their contents.
5. Discover Agent Skills only from immediate child directories matching skills/*/SKILL.md, with an exact SKILL.md filename and no recursive search for deeper skills.
6. Enforce plugin-root containment for the manifest, component directory, discovered SKILL.md files, and other package files Claude Code reads or executes. Apply the specification's narrowest failure boundary to paths that resolve outside the plugin root.
7. Treat a missing skills/ directory as valid. If skills is present but is not a directory, disable the skills component without invalidating independent components.
8. Validate each discovered skill against the Agent Skills specification. Skip and report an invalid skill while continuing to load valid sibling skills.
9. Ignore unsupported component types, including a portable mcp.json when Agent Plugins MCP support is not implemented, without preventing valid skills from loading.
10. Preserve existing native Claude plugin behavior for packages that do not declare an Agent Plugins schema. If both formats are present during a transition, treat .claude-plugin as Claude-specific compatibility data only and do not let it alter portable core metadata or fixed component discovery.

This request is intentionally limited to skills-only packages. Section 11.2 permits a conformant client to support one component type. Portable mcp.json transports, subprocess variables, and MCP lifecycle behavior can be considered separately.

Alternative Solutions

The current workaround is to ship both plugin.json and .claude-plugin/plugin.json with duplicated name, version, description, and author metadata. That keeps older clients working, but it creates a drift surface and still does not make Claude Code validate the portable manifest.

Another workaround is to put the portable and native packages in separate directories. That avoids mixed-format precedence, but it duplicates skills and defeats the goal of installing the same directory across clients.

A third workaround is to rely on the current generic root-manifest handling. That is what makes a simple package appear compatible today, but the missing and unsupported $schema checks show that this is format overlap rather than specification-aware support.

Related issue #80801 is not a duplicate. It proposes a shared .agents/ directory and manifest-declared resource paths. Agent Plugins 1.0.0 instead standardizes a root manifest, fixed component locations, validation semantics, and failure boundaries.

Priority

Medium - Would be very helpful

Feature Category

Developer tools/SDK

Use Case Example

1. I maintain a plugin package with a root plugin.json and two direct child skills under skills/.
2. The same directory is installed by multiple agent clients without copying or relocating the skills.
3. Claude Code recognizes the 1.0.0 schema, validates the portable core, enforces package containment, and loads the valid skills.
4. If one skill is invalid, Claude Code reports and skips it while continuing to load its valid sibling.
5. Legacy .claude-plugin data can remain during a transition for older Claude Code releases without becoming a second source of truth for portable metadata or discovery.
6. If the package claims an unsupported Agent Plugins version, installation or validation fails with a specific unsupported-version error instead of silently accepting it.

Additional Context

Observed with the stock Claude Code 2.1.240 distribution.

Published specification:
https://github.com/agentplugins/agent-plugins-spec/blob/main/spec/1.0.0.md

Canonical manifest schema:
https://agent-plugins.org/schemas/1.0.0/plugin.schema.json

Agent Skills specification:
https://agentskills.io/specification

A bounded acceptance suite would cover:

• A valid Agent Plugins 1.0.0 package loads each valid immediate-child skill from skills/*/SKILL.md.
• A package without skills/ loads without error.
• A nested skills/group/example/SKILL.md is not recursively discovered.
• An invalid skill is reported and skipped while a valid sibling still loads.
• A SKILL.md or component path that resolves outside the plugin root is skipped or rejected using the applicable containment boundary.
• A manifest missing $schema, name, or another required valid value is rejected before component discovery.
• A manifest declaring https://agent-plugins.org/schemas/999.0.0/plugin.schema.json is rejected with an unsupported-version diagnostic.
• An unknown top-level manifest field is reported and ignored while otherwise valid skills continue loading.
• A non-object extensions field is reported and ignored while otherwise valid skills continue loading.
• An object under an unimplemented extension namespace is ignored without validating its contents.
• A portable mcp.json does not prevent skills from loading when Agent Plugins MCP support is not implemented.
• A native root manifest without an Agent Plugins $schema retains the existing Claude plugin behavior.
• If .claude-plugin/plugin.json is present beside a portable root manifest, it cannot override the portable name, version, description, author, or fixed skill-discovery location.

The narrower skills-only scope is sufficient for the real plugin packages motivating this request and keeps portable MCP mapping out of this issue. Commands, hooks, agents, rules, and LSP servers are also outside Agent Plugins v1.

The specification places client-specific files under a stable reverse-domain extension namespace. A Claude-specific namespace and migration path for native components can be designed separately; this request only requires legacy native data not to override the portable core.