Guide · Agent skill

How to use the Plugin Structure agent skill for Claude Code

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The plugin-structure skill is a set of written guidance that an AI agent reads when you ask it to build a Claude Code plugin. It tells the agent the standard folder layout, where the plugin.json manifest must go, and how commands, agents, skills, hooks and MCP servers are arranged. This guide shows you how to install the skill, trigger it with plain requests, and check the results, even if you have never used agent skills before.

Claude Code Plugin Structure Guideanthropics/claude-plugins-official · Apache-2.0 Download the skill

Quick start

1Download and unzip. Download the skill ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder.
2Confirm Claude Code is available. The skill targets Claude Code's plugin system, so you need Claude Code to use it.
3Describe the plugin you want. Ask in plain words, for example to create a plugin with one command, and name the components you need.
4Review the folder layout. Check that plugin.json sits in .claude-plugin/ and that component folders are at the plugin root.
5Check the manifest. Confirm the name is kebab-case and every path is relative and starts with ./.
6Use the placeholder for paths. Make sure intra-plugin references use ${CLAUDE_PLUGIN_ROOT} rather than hardcoded paths.
7Test loading. Enable the plugin and run one of its commands to confirm Claude Code picks it up.

What the plugin-structure skill makes the agent do

When you ask the agent to create or organise a Claude Code plugin, the skill supplies the standard directory structure, the manifest rules and the naming conventions. Without it, the agent has to guess where files belong. With it, the agent builds files that Claude Code can discover automatically.

The skill is guidance for writing plugin files. It is not a tool that runs anything by itself, and the source does not describe it running scripts or making network calls.

Places the manifest at .claude-plugin/plugin.json
Keeps component folders (commands, agents, skills, hooks) at the plugin root
Uses kebab-case for directory and file names
Uses ${CLAUDE_PLUGIN_ROOT} for paths inside the plugin

How do you install the plugin-structure skill?

Download the ZIP for this skill from this page. Then choose one of two routes.

For Claude Code, unzip the download into ~/.claude/skills/ to make it available to you across projects, or into a project's .claude/skills/ folder to limit it to that project.

In the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

How do you trigger the skill with a natural request?

You do not need a special command. Describe the task in ordinary words. The skill's description lists phrases that should activate it, such as "create a plugin", "scaffold a plugin", "set up plugin.json", "add commands/agents/skills/hooks" and "configure auto-discovery".

Claude Code decides for itself when a skill is relevant, so state your goal clearly and name the component you care about.

"Create a plugin called code-review-assistant with a command and a hook."
"Set up plugin.json for my test-runner plugin."
"Where should the agent files go in my plugin, and what should they be named?"
"Why aren't the commands in my plugin showing up?"

What does a plugin folder built with this skill look like?

The skill's reference layout places the manifest in .claude-plugin/ and component folders at the top level. Only create folders for components your plugin actually uses.

The bundled examples show three sizes: a minimal plugin with one command, a standard plugin with commands, agents and skills, and an advanced enterprise-style plugin with MCP integration.

Minimal example: hello-world with .claude-plugin/plugin.json and commands/hello.md
Standard example: code-quality with commands, agents, skills, hooks and scripts
Advanced example: enterprise-devops with nested command, agent and skill folders

plugin-name/
├── .claude-plugin/
│   └── plugin.json
├── commands/
├── agents/
├── skills/
├── hooks/
│   └── hooks.json
├── .mcp.json
└── scripts/

What rules must a hand-written manifest follow?

The only required field in plugin.json is name, which must be kebab-case and unique across installed plugins. Recommended metadata includes version, description, author, license and keywords. Custom component paths supplement the default directories rather than replacing them, and they must be relative paths starting with ./.

Because mistakes in a hand-written manifest can stop a plugin loading, ask the agent to check names, paths and locations against the reference.

Name: kebab-case, no spaces or special characters
Version: semantic versioning (MAJOR.MINOR.PATCH)
Paths: relative to plugin root, start with ./, never absolute
Hooks and MCP servers: reference files with ${CLAUDE_PLUGIN_ROOT}, not hardcoded paths or ~/ shortcuts

{
  "name": "hello-world"
}

Which places should use ${CLAUDE_PLUGIN_ROOT}?

Use ${CLAUDE_PLUGIN_ROOT} for all references inside the plugin, such as hook command paths, MCP server arguments and script paths. The skill explains that plugins can install in different locations depending on the installation method, operating system and user preferences, so fixed paths break.

Hook commands
MCP server command arguments
Script execution references
Resource file paths in commands, agents and skills

bash ${CLAUDE_PLUGIN_ROOT}/scripts/run.sh

What people use it for

Scaffolding a first plugin with a single slash command, based on the minimal example
Organising an internal team plugin with commands, agents, skills and hooks in standard folders
Fixing a plugin whose commands or hooks are not being picked up by checking the layout and manifest paths
Adding a hook or MCP server to an existing plugin while keeping paths portable

Frequently asked questions

How do I install the plugin-structure skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one project. In the Claude apps, you can instead upload it under Settings, then Capabilities, then Skills.

Do I need Claude Code to use this skill?

Yes. The skill's guidance targets Claude Code's plugin system, and the source states it is not intended for projects outside Claude Code.

Does the skill run scripts or use the network?

According to the listing, it runs no scripts and uses no network access. It provides written guidance that the agent uses while writing plugin files.

Is the plugin-structure skill free?

The source gives its licence as Apache-2.0. This page does not state any price, so check the original repository for licence terms.

Why are my plugin's commands or hooks not being picked up?

Ask the agent to check the layout against this skill. Common causes described in the guidance are a manifest outside .claude-plugin/, component folders nested inside .claude-plugin/, non-kebab-case names, and paths that are absolute or do not start with ./.

What are the alternatives if this skill is not right for me?

If you only want to use an existing plugin, you do not need this skill. The source says it only helps build plugins. For other tasks, consult Claude Code's own plugin documentation or other skills in the directory.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you are building your first Claude Code plugin, standardising internal plugins, or debugging why components are not loading. Skip it if you only want to use existing plugins or work outside Claude Code, and always review hand-written manifests because small mistakes can stop a plugin loading.

Download the skill