Plugin Structure

What it is

Plugin Structure is a skill that covers Claude Code plugin architecture. Its topics are the standard directory layout, configuring the plugin.json manifest, organizing components (commands, agents, skills, hooks), auto-discovery, portable path references with ${CLAUDE_PLUGIN_ROOT}, and file naming conventions. Claude Code activates it when users ask to "create a plugin" or "scaffold a plugin", or need help understanding plugin structure, setting up plugin.json, adding commands/agents/skills/hooks, or configuring auto-discovery. The skill sets out several critical rules: - The manifest must live at .claude-plugin/plugin.json. - All component directories must sit at the plugin root, not inside .claude-plugin/. - Only create directories for components the plugin actually uses. - Use kebab-case for all directory and file names. On the manifest itself: - The only required field is name. - Recommended metadata includes version, description, author, homepage, repository, license and keywords. - Custom component paths supplement the default directories rather than replacing them. - Custom paths must be relative and start with ./. For each component type, the skill describes the location, format and discovery behavior: - Commands: .md files in commands/. - Agents: .md files in agents/. - Skills: subdirectories with SKILL.md. - Hooks: hooks/hooks.json or inline in the manifest. Events include PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact and Notification. - MCP servers: .mcp.json or inline in the manifest. It stresses using ${CLAUDE_PLUGIN_ROOT} for all intra-plugin paths, because plugins install in different locations depending on the installation method, the operating system and user preferences. It also covers best practices, common patterns (minimal, full-featured, skill-focused) and troubleshooting. The skill uses progressive disclosure: 1. A lean SKILL.md of about 1600 words. 2. References of about 6000 words: manifest-reference.md and component-patterns.md. 3. Examples of about 8000 words: minimal-plugin.md, standard-plugin.md and advanced-plugin.md. Claude loads the references and examples only as needed. The skill works well alongside the hook-development, mcp-integration and marketplace-publishing skills.

Who it's for

• Developers creating or scaffolding Claude Code plugins
• Plugin authors setting up or configuring plugin.json manifests
• Developers organizing commands, agents, skills, hooks, and MCP servers within a plugin
• Anyone troubleshooting plugin component loading, path resolution, or auto-discovery issues

Requirements

Examples

create a plugin

{
  "name": "plugin-name"
}

{
  "PreToolUse": [{
    "matcher": "Write|Edit",
    "hooks": [{
      "type": "command",
      "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate.sh",
      "timeout": 30
    }]
  }]
}

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/server.js"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}