Set up and review a Claude Code plugin structure

This guide turns Anthropic's official plugin-structure guidance into a reviewable setup workflow. It is useful for a new plugin and for migrating an existing .claude customization into a distributable extension.

Create the plugin root and manifest

Start with a dedicated plugin root containing the .claude-plugin directory. The plugin.json file belongs only inside that directory. Begin with a unique kebab-case name and add description, version, author, repository, and license metadata only when the team can keep those details accurate.

Place components at the correct level

Do not place skills, agents, commands, or hooks inside .claude-plugin. These directories belong directly at the plugin root. Give each skill its own directory with a SKILL.md file. One skill is enough for a small plugin. As the project grows, the skills layout makes organization clearer and preserves a predictable namespace. Create only the component types the plugin actually needs.

Keep paths portable

Review every path used by hooks, MCP configuration, and scripts. Use CLAUDE_PLUGIN_ROOT so the extension can reach its own files regardless of where it is installed. Absolute paths and assumptions about the current working directory commonly fail when a plugin is loaded from a marketplace, a local folder, or a shared team location.

Test locally and inspect changes

Launch Claude Code for a local test with the plugin directory option and then try the namespaced skill invocation. Check the help interface, loaded components, and any reported errors. If installation asks for plugin reloading, reload the plugins. A successful load does not prove that a hook, MCP server, or script is secure or appropriate for a production workflow.

Review security before distribution

Read every hook and script before sharing the plugin. Inspect file writes, network connections, environment variables, secrets, and possible changes to external systems. Apply least privilege and require human confirmation for risky operations. Document runtime dependencies and version assumptions. This keeps the structure reproducible while making clear that an architecture guide is not an automated security guarantee.