Plugin Structure — Claude Code Skills Teardown

Plugin Structure — Claude Code Skills Teardown

Claude Code plugins follow a standardized directory layout: a manifest in .claude-plugin/, and component directories — commands/, agents/, skills/, hooks/ — at the plugin root. Auto-discovery means you add a file to the right directory and it loads; no registration step needed. But the manifest-in-.claude-plugin vs components-at-root placement rule is the most common silent failure. This teardown walks through the full directory anatomy, the five component types, the ${CLAUDE_PLUGIN_ROOT} portable-path law, and where the skill gets it right — and where it bites.

0:00 Intro 0:40 Directory Layout + Manifest 1:41 Component Types + Paths 2:44 Teardown: Gets Right / Where It Bites 3:59 Verdict 4:42 Your Turn 5:30 Outro

YOUR TURN: Open a Claude Code session. Paste this prompt: "Create a plugin called code-review-assistant that has a review command, a code-reviewer agent, and an api-testing skill." Watch four things: (1) Does Claude place the manifest at .claude-plugin/plugin.json, not at the plugin root? (2) Does Claude place commands/, agents/, and skills/ at the plugin root, not inside .claude-plugin/? (3) Does the skill directory contain a file named exactly SKILL.md? (4) Does any hook configuration use ${CLAUDE_PLUGIN_ROOT} for its command path?

Source: anthropics/claude-code plugins/plugin-dev/skills/plugin-structure/SKILL.md

Liam, in for Bear · @NikBearBrown

Every claim in this video was fact-checked against the source material before rendering.

▶ The full series playlist — Brutalist https://www.youtube.com/playlist?list=PLG9H-C6rp5RU

What this video covers

• 0:00 — Intro
• 0:40 — Directory Layout + Manifest
• 1:41 — Component Types + Paths
• 2:44 — Teardown: Gets Right / Where It Bites
• 3:59 — Verdict
• 4:42 — Your Turn
• 5:30 — Outro

Transcript

A lightly formatted transcript of the video, with timestamps so you can jump to any section on YouTube.

Intro

[0:00] Guten Tag, this is Liam in for Bear. Ask Claude to create a plugin, scaffold a plugin structure, understand directory layout, set up plugin. JSON or organize plugin components, the plugin structure skill fires. Claude code plugins follow a standardized layout, a manifest in the dot Claude plugin directory and component directories commands, agents, skills, hooks at the plugin root. Auto discovery means you add a file to the right directory and it loads, no registration step. Use dollar sign Claude plugin root for every path reference in hooks and MCP config, so the plugin works regardless of where it's installed. Let me walk you through the directory layout, the five component types, and where this skill gets it right and where it bites. The directory

Directory Layout + Manifest

[0:40] Layout, every plugin has a root directory with this structure. A Claude plugin subdirectory holding plugin. JSON, the manifest, and component directories at the plugin root level. Commands for slash commands, agents for sub agent definitions, skills for skill. MD base skills in subdirectories, hooks for hooks. JSON and its scripts, MCP JSON for MCP server definitions and scripts for shared utilities. The two critical rules, the manifest must be in Claude plugin not at the root and the component directories must be at the root not inside Claude plugin. This mistake is common and silent. Misplacing either means components don't load. The manifest plugin JSON has one required field name in kebab case. Everything else is optional recommended metadata. Version following semantic versioning, description, author, homepage, repository, license. Keywords, custom paths in the manifest supplement auto discovery. They don't replace it. If you set a custom agents path, the default agents directory is still scanned. The only naming rules, kebab case everywhere for all directories and files. Five component types. Commands, markdown

Component Types + Paths

[1:43] Files in the commands directory with YAML frontmatter any MD file auto loads as a slash command. Agents, markdown files in the agents directory auto loaded invocable manually or selected automatically by Claude code based on task context. Skills, each skill gets its own subdirectory inside skills and must have a file named skill.md, not readme.md, not skill.md, exactly skill.md. For auto discovery, hooks a hooks.json configuration file in the hooks directory with scripts in a scripts subdirectory. Hooks register automatically on plugin enable. MCP servers a MCP.json file at the plugin root or inline in plugin. json, the portable path rule. Use dollar sign cloud plugin root in every hook command MCP server argument and script reference. Never use hard-coded absolute paths. Never use relative paths from the working directory. Never use tilde expansions. Plugins install in different locations depending on how users install them. Only cloud plugin root resolves correctly in all contexts. The variable is available as an environment variable inside hook scripts. Here's the

Teardown: Gets Right / Where It Bites

[2:44] Teardown. Plugin structure gets auto discovery right. Commands, agents, and skills all load automatically from their directories. No registration step, no imports, just put the file in the right place. The cloud plugin root variable is clearly documented as required for all inter plugin paths with an explicit list of what never to use, absolute paths, working directory relatives, home shortcuts. Three layout patterns, minimal, full featured, skill focused. Cover the practical range. The troubleshooting section maps common failures to causes. Component not loading, path resolution errors, auto discovery not working. Where bites the manifest in cloud plugin versus components at root rule is the most common mistake and gets one mention in critical rules, but is never reinforced in the component sections. Custom paths supplementing rather than replacing defaults is easy to miss and leads to double loading when both a custom path and the default directory exist. The skill states no restart required for changes, but the hook development skill says restart is required. Inconsistent guidance for the same life cycle event. Skill.md is the required file name for skill discovery and a misnamed file produces silent failure. This is buried in the skill subsection. And command name collisions between two plugins produce silent conflicts with no resolution mechanism documented. Verdict

Verdict

[3:59] Plugin structure fires for creating plugins, understanding directory layout, setting up plugin.json or organizing component manifest in cloud plugin {slash} plugin.json required field name in kebab case. Components at plugin root command {slash} {slash} commands.md agent {slash} md skill {slash} skill.md subdirs hook {slash} hooks.json mcp.json auto discovery no registration step. Just file in the right place. Dollar cloud plugin root for all path references never hard code. Custom path supplement defaults not replace gaps. Cloud plugin vs root placement rule silent on failure. Supplement not replace easily missed. Restart inconsistency with hook development skill. md exact name undiscoverable. Command collision no resolution. Your

Your Turn

[4:42] Turn. Open a cloud code session. Paste this. Create a plugin called code review assistant that has a review command, a code reviewer agent, and an API testing skill. Watch four things. First, does cloud place the manifest at cloud plugin {slash} plugin.json not at the plugin root. Second, does cloud place commands, agents, and skills directories at the plugin root not inside cloud plugin. Third, does the skill directory contain a file named exactly skill.md not readme.md not skill.md. And fourth, does any hook configuration use dollar sign cloud plugin root for its command path rather than a hard coded or working directory relative path. If the manifest is a plugin.json at the root placement is wrong. If a directory called cloud plugin {slash} commands exists, components are misplaced. If the skill file is named anything other than skill.md, it will not be discovered. Those are your gates. Plugin structure lay them in for bear.