claude-engineering-plugin/docs/specs/claude-code.md

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. citeturn2view7
• The .claude-plugin/ directory only holds the manifest; component directories (commands/agents/skills/hooks) must be at the plugin root, not inside .claude-plugin/. citeturn2view7
• 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. citeturn2view7

Manifest schema (.claude-plugin/plugin.json)

• name is required and must be kebab-case with no spaces. citeturn2view8
• Metadata fields include version, description, author, homepage, repository, license, and keywords. citeturn2view8
• 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. citeturn2view8turn2view9
• Custom paths supplement defaults; they do not replace them, and all paths must be relative to the plugin root and start with ./. citeturn2view9

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. citeturn6search0

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. citeturn2view7
• Skills can be invoked with /<skill-name> and are stored in ~/.claude/skills or .claude/skills (project-level); plugins can also ship skills. citeturn12view0
• Skill frontmatter examples include name, description, and optional allowed-tools. citeturn12view0

Agents (agents/*.md)

• Agents are markdown files with frontmatter such as description and capabilities, plus descriptive content for when to invoke the agent. citeturn2view7

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. citeturn2view7
• Plugin hooks are merged with user and project hooks when the plugin is enabled, and matching hooks run in parallel. citeturn1search0
• Supported events include PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Notification, Stop, SubagentStart, SubagentStop, Setup, SessionStart, SessionEnd, and PreCompact. citeturn2view7
• Hook types include command, prompt, and agent. citeturn2view7
• Hooks can use ${CLAUDE_PLUGIN_ROOT} to reference plugin files. citeturn1search0

MCP servers

• Plugins can define MCP servers in .mcp.json or inline under mcpServers in the manifest. Configuration includes command, args, env, and cwd. citeturn2view7turn2view10
• Plugin MCP servers start automatically when enabled and appear as standard MCP tools. citeturn2view10

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. citeturn2view7turn2view10

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). citeturn2view12
• To access external files, use symlinks inside the plugin directory or restructure your marketplace so the plugin root contains shared files. citeturn2view12

Marketplace schema (.claude-plugin/marketplace.json)

• A marketplace JSON file lists plugins and includes fields for marketplace metadata and a plugins array. citeturn8view2
• Each plugin entry includes at least a name and source and can include additional manifest fields. citeturn8view2