plugin-structure_skill

Overview

This skill explains the canonical Claude Code plugin structure, manifest rules, and component organization to help you scaffold maintainable, portable plugins. It focuses on directory layout, manifest configuration, path portability, and auto-discovery rules so your plugin integrates reliably with Claude Code. Use it to align naming, file placement, and runtime references with platform expectations.

How this skill works

It inspects and prescribes a standard plugin root layout with a hidden manifest directory containing plugin.json, plus top-level component directories for commands, agents, skills, hooks, and optional server definitions. The skill describes how Claude Code auto-discovers components, how to declare custom component paths in the manifest, and where to use the ${CLAUDE_PLUGIN_ROOT} variable for portable paths. It also outlines naming conventions, discovery timing, and error checks to troubleshoot common load problems.

When to use it

• Scaffolding a new Claude Code plugin from scratch
• Organizing components (commands, agents, skills, hooks) in an existing plugin
• Configuring plugin.json with custom component paths or MCP server entries
• Portabilizing scripts and hooks using ${CLAUDE_PLUGIN_ROOT} references
• Troubleshooting why a component is not being discovered or loaded

Best practices

• Keep plugin.json minimal; only add custom paths when necessary and use relative paths starting with ./
• Place commands, agents, skills, and hooks at the plugin root (not inside the manifest folder)
• Use kebab-case for all file and directory names and descriptive, consistent naming across components
• Always reference internal files via ${CLAUDE_PLUGIN_ROOT} in manifests, hooks, and scripts to ensure portability
• Group related components and include concise documentation inside component folders to aid maintenance

Example use cases

• Minimal utility plugin with a single slash command and a minimal manifest for quick installs
• Full-featured plugin exposing commands, specialized agents, auto-activating skills, hooks, and MCP server definitions
• Skill-focused plugin that provides multiple autonomous skills with supporting scripts and examples
• Hook-driven plugin that validates or formats code automatically before tools run using executable scripts