holocron/plugins/kyberforge/skills/marketplace-architect/references/claude-code.md

Claude Code Plugin Reference

Verified against code.claude.com/docs as of June 2026.

---

Directory structure

plugin-root/
├── .claude-plugin/
│   └── plugin.json       # ONLY plugin.json goes here; all other dirs at plugin root
├── skills/               # skill directories: <name>/SKILL.md
├── commands/             # legacy flat .md files; promote to skills/ for new plugins
├── agents/               # agent definitions: <name>.md
├── hooks/
│   └── hooks.json
├── .mcp.json
├── .lsp.json
├── monitors/
│   └── monitors.json
├── bin/                  # executables added to PATH while plugin is enabled
└── settings.json         # default settings applied when plugin is enabled

A plugin that ships exactly one skill may place SKILL.md directly at the plugin root. Use skills/ for plugins that may grow beyond one skill.

---

plugin.json schema

{
  "name": "my-plugin",              // kebab-case, no spaces — also the skill namespace prefix
  "displayName": "My Plugin",       // human-readable; shown in UI (v2.1.143+)
  "description": "What it does",
  "version": "1.0.0",              // OPTIONAL — omit to use git SHA per commit
  "author": { "name": "Name", "url": "https://..." },
  "homepage": "https://...",
  "repository": "https://github.com/...",
  "license": "MIT",
  "keywords": [],
  "defaultEnabled": true,          // set false to install disabled (v2.1.154+)
  "dependencies": [
    { "name": "other-plugin", "version": "~2.1.0" }
  ]
}

Only name is required. Add fields only when needed.

---

marketplace.json schema

{
  "name": "my-ai-marketplace",
  "owner": { "name": "Your Name", "email": "you@example.com" },
  "description": "Description",
  "version": "1.0.0",
  "plugins": [
    {
      "name": "startup-cto",
      "source": "./plugins/startup-cto",
      "description": "...",
      "strict": true
    }
  ]
}

description and version are also accepted under a metadata key for backward compatibility.

---

Plugin source types

Type	Format	Notes
Relative path	"./plugins/my-plugin"	Must start with ./. Resolved from marketplace root. Only works with git-hosted marketplaces, not URL-based.
GitHub	{ "source": "github", "repo": "owner/repo", "ref": "main", "sha": "abc123" }	sha pins exact commit; ref is branch/tag
URL / git	{ "source": "url", "url": "https://...", "ref": "main" }	also accepts owner/repo shorthand and SSH URLs
git-subdir	{ "source": "git-subdir", "url": "...", "path": "packages/my-plugin" }	sparse clone of a monorepo path
npm	{ "source": "npm", "package": "@scope/pkg", "version": "^2.0.0", "registry": "https://..." }	installed via npm install

When both ref and sha are set, sha is the effective pin.

---

Strict mode

Controls whether plugin.json is the authority for component definitions.

• strict: true (default) — plugin has its own plugin.json; marketplace entry can add extra skills/hooks on top.
• strict: false — marketplace entry is the entire definition; plugin needs no plugin.json. The entry declares skills, agents, hooks, mcpServers path arrays.

Do not use strict: false plus a component-declaring plugin.json — this is a conflict and fails to load.

---

Reserved marketplace names

These names are blocked for third-party use: claude-code-marketplace, claude-code-plugins, claude-plugins-official, claude-plugins-community, claude-community, anthropic-marketplace, anthropic-plugins, agent-skills, anthropic-agent-skills, knowledge-work-plugins, life-sciences, claude-for-legal, claude-for-financial-services, financial-services-plugins

Names that impersonate official marketplaces are also blocked (e.g. official-claude-plugins, anthropic-tools-v2).

Plugin names must be kebab-case (lowercase, digits, hyphens). Claude.ai marketplace sync rejects anything else even if the local CLI tolerates it.

---

Version management

• If version is set in plugin.json, users receive updates only when you bump it.
• If version is omitted, git commit SHA is used — every commit is a new version.
• If version is set in both plugin.json and the marketplace entry, plugin.json wins silently.
• Recommendation: omit version unless you need explicit release gates.

---

Environment variables

• ${CLAUDE_PLUGIN_ROOT} — absolute path to the plugin's installation directory. Use in hook commands and MCP/LSP configs for all in-plugin file references. This path changes on update.
• ${CLAUDE_PLUGIN_DATA} — persistent directory for plugin state that survives updates. Use for node_modules, generated code, caches.

---

Validation and CLI commands

# Validate plugin structure and manifest
claude plugin validate ./my-plugin
claude plugin validate ./my-plugin --strict   # treat warnings as errors

# Install/manage
claude plugin install <name>@<marketplace>
claude plugin update <name>@<marketplace>
claude plugin uninstall <name>
claude plugin list
claude plugin enable <name>
claude plugin disable <name>

# Marketplace
claude plugin marketplace add owner/repo
claude plugin marketplace update

# Development
claude --plugin-dir ./my-plugin               # load without installing
claude --plugin-dir ./my-plugin.zip           # load from zip (v2.1.128+)
claude plugin init my-tool                    # scaffold a skills-dir plugin

---

Key gotchas

1. Plugins are copied to cache on install. Cannot reference ../shared-utils — those files are not copied. Duplicate shared files into each plugin or use symlinks.
2. commands/ ≠ skills/. Flat foo.md is a legacy command; foo/SKILL.md is a skill. Promote flat commands to skill directories during migration.
3. Only plugin.json in .claude-plugin/. Skills, agents, hooks, and other directories must be at the plugin root, not inside .claude-plugin/.
4. Plugin names are skill namespace prefixes. name: my-plugin means skills invoke as /my-plugin:skill-name.
5. defaultEnabled: false requires v2.1.154+. Earlier versions ignore it and enable on install.