A Brief History of plugin.json

The evolution of Claude Code's plugin manifest system into a full-fledged dependency management engine.

1. The Era of Fragmentation (Late 2025)

When Anthropic first stabilized the Claude Code CLI and the Model Context Protocol (MCP), extendability was highly fragmented.

• MCP Servers handled external tools (APIs, databases, filesystems).
• Settings files (.claude/settings.json) handled rules and configurations.
• Skills (like custom prompts) lived as standalone instruction documents.
• No unified concept of a "packaged extension" existed; workflows had to be manually wired together via scripts.

2. The Birth of the Manifest: .claude-plugin/plugin.json (Early 2026)

Anthropic introduced the Claude Code Plugin Architecture to unify components into a singular standalone structure.

• Plugins bundled skills, custom sub-agents, hooks, and local .mcp.json tool declarations.
• Introduced plugin.json as a passive metadata descriptor handling basic identity and simple version strings.
• Versioning remained loose, resolving primarily by binding a project path to whatever git SHA happened to be HEAD at runtime.

{
  "name": "deploy-kit",
  "description": "Handles infrastructure provisioning and AWS EKS hooks",
  "version": "1.0.0"
}

3. The Broken Cache & Chaos Crisis (Spring 2026)

As enterprise adoption scaled, major operational and environmental cracks emerged in production environments.

• Non-Deterministic Environments: Shifting git SHAs caused different team members to resolve different variations of the same plugin.
• Cache Nightmares: Broken builds cached locally (~/.claude/plugins/cache/) persisted indefinitely due to a lack of native self-healing mechanisms.
• Silent Failures: Master plugins relying on utility plugins had no mechanism to declare relationships, leading to fragile manual setup guides.

4. The Modern Era: Pure Parity & Version Constraints (June 2026)

Anthropic rolled out native Plugin Dependency Resolution (v2.1.143+), transforming plugin.json into an active package manager specification heavily inspired by Node's package.json.

• Graph Enforcement: The CLI actively blocks disabling a plugin if active core systems rely on it, tracking the entire transitive dependency graph.
• Cross-Marketplace Guardrails: Auto-installing dependencies across disparate marketplaces is locked down by default to prevent supply-chain attacks.
• Strict Release Tagging: Enforced tag pushing (claude plugin tag --push) matches git tags directly to the manifest version.

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

This structural shift marks the transition of AI tools away from loose "prompt scripts" and into production-grade, tightly governed software engineering components.

All content above provided by courtesy of Gemini. No claims mine.