Add dependencies field to plugin manifest

[pabloubal]

Problem

The current v1.0.0 schema for plugin.json has additionalProperties: false with no way to declare that a plugin depends on another plugin. Plugins that compose functionality from other plugins have no portable way to express this.

We've found it extremely useful to build our plugins ecosystem in layers with dependencies. Without dependencies there might be a tendency to either duplicate specs in the skills, or rely on each user to understand the dependencies and install them.

I see that the FUTURE_CONSIDERATIONS.md already lists dependency resolution as a planned. I just want to create this concrete proposal to move it forward.

Proposal

Version contraints might be good for external dependencies, but a challenge within a marketplace.

"dependencies": {
    "type": "object",
    "description": "Other plugins that must be resolved and loaded before this plugin.",
    "additionalProperties": {
      "$ref": "#/$defs/dependency"
    }
  }

  "$defs": {
    "dependency": {
      "title": "Plugin dependency",
      "type": "object",
      "properties": {
        "source": {
          "$ref": "#/$defs/source"
        }
      },
      "required": ["source"],
      "additionalProperties": false
    },
    "source": {
      "title": "Plugin source",
      "oneOf": [
        { "$ref": "#/$defs/localSource" },
        { "$ref": "#/$defs/externalSource" }
      ]
    },
    "localSource": {
      "title": "Local source",
      "description": "A dependency co-located in the same repository, resolved relative to the marketplace root.",
      "type": "object",
      "properties": {
        "path": {
          "type": "string",
          "pattern": "^\\./"
        }
      },
      "required": ["path"],
      "additionalProperties": false
    },
    "externalSource": {
      "title": "External source",
      "description": "A dependency resolved from a remote git repository, optionally scoped to a subdirectory and ref.",
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "pattern": "^https://",
          "description": "Git repository URL."
        },
        "path": {
          "type": "string",
          "description": "Path to the plugin root within the repository. Defaults to the repository root when omitted."
        },
        "ref": {
          "type": "string",
          "description": "Git ref (tag, branch, or commit SHA). Defaults to the repository default branch when omitted."
        }
      },
      "required": ["url"],
      "additionalProperties": false
    }
  }

Example

Local dependency

{
    "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
    "name": "a-team",
    "version": "1.0.0",
    "description": "A-team workflow skills.",
    "author": { "name": "A-Team" },
    "dependencies": {
      "architecture-team": {
        "source": {
          "path": "./plugins/architecture-team"
        }
      }
    }
  }

Remote dependency

  {
    "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
    "name": "a-team",
    "version": "1.0.0",
    "description": "A-team workflow skills.",
    "author": { "name": "A-Team" },
    "dependencies": {
      "architecture-team": {
        "source": {
          "url": "https://github.com/my-org/architecture-team-plugin",
          "ref": "v2.1.0"
        }
      }
    }
  }

Current workaround

We are placing dependencies as an unknown top-level field, which the spec treats as non-fatal but schema-invalid. Using extensions["com.example.client"] is spec-conformant but not portable across clients.

Some considerations

• What is the resolution order for transitive dependencies?
• How should clients handle a missing dependency? Whether it should halt the installation of the plugin or continue.

[jonathanhefner]

I see that the FUTURE_CONSIDERATIONS.md already lists dependency resolution as a planned. I just want to create this concrete proposal to move it forward.

I think that file may be out of date. 😅 I will take into updating it.

My personal opinion is that plugins should be monolithic units, with no required dependencies between them.

For distributing multiple plugins together, I would recommend going up one abstraction layer to something like AI Catalog (or ARD, which is built on top of AI Catalog).

[digitarald]

New implementation evidence from Claude Code and Copilot

Claude Code now ships plugin-to-plugin dependencies with this core shape:

"dependencies": [
  "audit-logger",
  { "name": "secrets-vault", "version": "~2.1.0" }
]

Claude resolves bare names in the declaring plugin's marketplace, installs dependencies recursively, intersects semver constraints, selects the highest matching tagged version, and preserves the existing working graph when a new constraint conflicts. Cross-marketplace dependencies require an explicit allowlist on the root marketplace. The official behavior is documented at https://code.claude.com/docs/en/plugin-dependencies.

GitHub Copilot is exploring the same minimal item shape in https://github.com/github/copilot-agent-runtime/issues/21386, initially under extensions.com.github.copilot. The proposed first version is narrower than Claude's model. It only allows required same-catalog dependencies and does not allow source URLs, cross-catalog lookup, lockfiles, optional dependencies, or raw Skill and MCP dependencies.

OpenAI Codex does not currently resolve plugin dependencies. Its marketplace parser can preserve Claude-style entry metadata, but installation materializes one requested entry and does not traverse a graph. This makes Claude and Copilot the concrete resolver implementations under consideration, not three aligned clients.

There is some early community use, but official catalogs do not appear to depend on it yet. A GitHub code-search snapshot on 2026-09-22 found 377 textual dependencies matches among 25,728 .claude-plugin/plugin.json matches. Several of those use the field for packages or binaries rather than plugins. For Codex catalogs, only two of nine dependency-search hits had real entry-level plugin dependencies, and Codex does not enforce them.

The remaining portable question is identity and resolution context. Agent Plugins deliberately has no durable plugin ID, so name alone only works inside a marketplace or catalog.

Could the TSC clarify which direction it prefers for a future version?

1. Standardize a small required-plugin declaration and leave resolution to clients or distribution systems.
2. Keep dependencies client-specific under extensions.
3. Require dependencies to reference an external catalog identity, such as an AI Catalog identifier.

A narrow portable declaration could use name plus an optional semver range. Installer behavior, cross-catalog sources, lockfiles, optional dependencies, and activation or permission policy could remain outside the core spec.

Related: marketplace/index discussion #52, distribution discussion #53, and AI Catalog dependency PR #95.

🤖 Posted by GitHub Copilot on Harald's behalf.