plugin-structure

Guides creation of Claude Code plugins with manifest configuration and component organization.

Updated Oct 7, 2022
One-click install
npx skills add https://github.com/tamagusko/linux-cfg --skill plugin-structure-tamagusko
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: plugin-structure
Source: https://github.com/tamagusko/linux-cfg/tree/main/dotfiles/claude/skills/plugin-structure
Command: npx skills add https://github.com/tamagusko/linux-cfg --skill plugin-structure-tamagusko

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Building a Claude Code plugin requires knowing the exact directory layout, manifest fields, and auto-discovery rules, and getting any of these wrong means components silently fail to load. ## Core Features & Use Cases - Directory Layout Guidance: Explains the required .claude-plugin/plugin.json location and root-level component directories for commands, agents, skills, and hooks. - Manifest Reference: Documents every plugin.json field including name, version, author, custom component paths, and path resolution rules. - Portable Path Patterns: Shows how to use ${CLAUDE_PLUGIN_ROOT} so hooks, MCP servers, and scripts work regardless of install location. - Use Case: You want to scaffold a new plugin with a slash command, a subagent, and a PreToolUse hook; this skill walks you through the manifest, file naming conventions, and auto-discovery behavior so everything registers correctly on the first try. ## Quick Start Ask Claude to scaffold a new Claude Code plugin with a command, an agent, and a hook, following the standard plugin directory structure.

Frequently Asked Questions about plugin-structure

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a Claude Code plugin?

Create a directory with .claude-plugin/plugin.json containing at least a kebab-case name field, then add component directories like commands/, agents/, or skills/ at the plugin root. Claude Code auto-discovers all .md files in these directories when the plugin is enabled.

Where should plugin.json be located in a Claude Code plugin?

The plugin.json manifest must be inside the .claude-plugin/ directory at the plugin root. Component directories like commands/ and agents/ must sit at the plugin root level, not nested inside .claude-plugin/.

What is ${CLAUDE_PLUGIN_ROOT} used for in plugins?

${CLAUDE_PLUGIN_ROOT} is an environment variable that resolves to the plugin's install location, used for hook commands, MCP server arguments, and script references. It keeps plugins portable since install paths vary by user, OS, and installation method.

Why is my Claude Code plugin command not loading?

Common causes are incorrect directory placement, missing or malformed YAML frontmatter, or wrong file naming. Verify the file is a .md file in commands/ at the plugin root, uses kebab-case naming, and that the plugin is enabled.

Can I use custom directories for plugin components?

Yes, the commands, agents, hooks, and mcpServers fields in plugin.json accept custom paths, which must be relative, start with ./, and use forward slashes. Custom paths supplement the default directories rather than replacing them.