e97f85bd53
* Add OpenCode converter coverage and specs * Add Codex target support and spec docs * Generate Codex command skills and refresh spec docs * Add global Codex install path * fix: harden plugin path loading and codex descriptions * feat: ensure codex agents block on convert/install * docs: clarify target branch usage for review * chore: prep npm package metadata and release notes * docs: mention opencode and codex in changelog * docs: update CLI usage and remove stale todos * feat: install from GitHub with global outputs
68 lines
4.6 KiB
Markdown
68 lines
4.6 KiB
Markdown
# Claude Code Plugin Spec
|
|
|
|
Last verified: 2026-01-21
|
|
|
|
## Primary sources
|
|
|
|
```
|
|
https://docs.claude.com/en/docs/claude-code/plugins-reference
|
|
https://docs.claude.com/en/docs/claude-code/hooks
|
|
https://docs.claude.com/en/docs/claude-code/slash-commands
|
|
https://docs.claude.com/en/docs/claude-code/skills
|
|
https://docs.claude.com/en/docs/claude-code/plugin-marketplaces
|
|
```
|
|
|
|
## Plugin layout and file locations
|
|
|
|
- A plugin root contains `.claude-plugin/plugin.json` and optional default directories like `commands/`, `agents/`, `skills/`, `hooks/`, plus `.mcp.json` and `.lsp.json` at the plugin root. citeturn2view7
|
|
- The `.claude-plugin/` directory only holds the manifest; component directories (commands/agents/skills/hooks) must be at the plugin root, not inside `.claude-plugin/`. citeturn2view7
|
|
- The reference table lists default locations and notes that `commands/` is the legacy home for skills; new skills should live under `skills/<name>/SKILL.md`. citeturn2view7
|
|
|
|
## Manifest schema (`.claude-plugin/plugin.json`)
|
|
|
|
- `name` is required and must be kebab-case with no spaces. citeturn2view8
|
|
- Metadata fields include `version`, `description`, `author`, `homepage`, `repository`, `license`, and `keywords`. citeturn2view8
|
|
- Component path fields include `commands`, `agents`, `skills`, `hooks`, `mcpServers`, `outputStyles`, and `lspServers`. These can be strings or arrays, or inline objects for hooks/MCP/LSP. citeturn2view8turn2view9
|
|
- Custom paths supplement defaults; they do not replace them, and all paths must be relative to the plugin root and start with `./`. citeturn2view9
|
|
|
|
## Commands (slash commands)
|
|
|
|
- Command files are Markdown with frontmatter. Supported frontmatter includes `allowed-tools`, `argument-hint`, `description`, `model`, and `disable-model-invocation`, each with documented defaults. citeturn6search0
|
|
|
|
## Skills (`skills/<name>/SKILL.md`)
|
|
|
|
- Skills are directories containing `SKILL.md` (plus optional support files). Skills and commands are auto-discovered when the plugin is installed. citeturn2view7
|
|
- Skills can be invoked with `/<skill-name>` and are stored in `~/.claude/skills` or `.claude/skills` (project-level); plugins can also ship skills. citeturn12view0
|
|
- Skill frontmatter examples include `name`, `description`, and optional `allowed-tools`. citeturn12view0
|
|
|
|
## Agents (`agents/*.md`)
|
|
|
|
- Agents are markdown files with frontmatter such as `description` and `capabilities`, plus descriptive content for when to invoke the agent. citeturn2view7
|
|
|
|
## Hooks (`hooks/hooks.json` or inline)
|
|
|
|
- Hooks can be provided in `hooks/hooks.json` or inline via the manifest. Hooks are organized by event → matcher → hook list. citeturn2view7
|
|
- Plugin hooks are merged with user and project hooks when the plugin is enabled, and matching hooks run in parallel. citeturn1search0
|
|
- Supported events include `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `UserPromptSubmit`, `Notification`, `Stop`, `SubagentStart`, `SubagentStop`, `Setup`, `SessionStart`, `SessionEnd`, and `PreCompact`. citeturn2view7
|
|
- Hook types include `command`, `prompt`, and `agent`. citeturn2view7
|
|
- Hooks can use `${CLAUDE_PLUGIN_ROOT}` to reference plugin files. citeturn1search0
|
|
|
|
## MCP servers
|
|
|
|
- Plugins can define MCP servers in `.mcp.json` or inline under `mcpServers` in the manifest. Configuration includes `command`, `args`, `env`, and `cwd`. citeturn2view7turn2view10
|
|
- Plugin MCP servers start automatically when enabled and appear as standard MCP tools. citeturn2view10
|
|
|
|
## LSP servers
|
|
|
|
- LSP servers can be defined in `.lsp.json` or inline in the manifest. Required fields include `command` and `extensionToLanguage`, with optional settings for transport, args, env, and timeouts. citeturn2view7turn2view10
|
|
|
|
## Plugin caching and path limits
|
|
|
|
- Claude Code copies plugin files into a cache directory instead of using them in place. Plugins cannot access paths outside the copied root (for example, `../shared-utils`). citeturn2view12
|
|
- To access external files, use symlinks inside the plugin directory or restructure your marketplace so the plugin root contains shared files. citeturn2view12
|
|
|
|
## Marketplace schema (`.claude-plugin/marketplace.json`)
|
|
|
|
- A marketplace JSON file lists plugins and includes fields for marketplace metadata and a `plugins` array. citeturn8view2
|
|
- Each plugin entry includes at least a `name` and `source` and can include additional manifest fields. citeturn8view2
|