holocron/.agents/skills/marketplace-architect/references/claude-code.md

# Claude Code Plugin Reference

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

---

## Directory structure

```text
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

```json
{
  "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

```json
{
  "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

```bash
# 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.