---

name: plugin-structure description: Claude Code plugin structure and requirements. Use when creating, validating, or troubleshooting plugins. Covers plugin.json schema, SKILL.md format, command frontmatter, and agent configuration. allowed-tools: Read, Glob, Grep

Claude Code Plugin Structure

This skill provides comprehensive knowledge about Claude Code plugin development, including directory structure, manifest formats, and component requirements.

Plugin Directory Layout

A properly structured Claude Code plugin follows this hierarchy:

Copymy-plugin/
├── .claude-plugin/
│   └── plugin.json          # Required - Plugin manifest
├── commands/                # Optional - Slash commands
│   └── command-name.md
├── agents/                  # Optional - Custom agents
│   └── agent-name.md
├── skills/                  # Optional - Agent skills
│   └── skill-name/
│       └── SKILL.md
├── hooks/                   # Optional - Event handlers
│   └── hooks.json
├── .mcp.json               # Optional - MCP server config
└── README.md               # Recommended - Documentation

Critical Rules:

1. Directories (commands/, agents/, skills/, hooks/) MUST be at plugin root, NOT inside .claude-plugin/
2. Skills MUST use subdirectory format: skills/skill-name/SKILL.md
3. Empty directories should be removed

plugin.json Schema

Location: .claude-plugin/plugin.json

Required Fields

Copy{
  "name": "my-plugin",
  "description": "Brief description of plugin purpose",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

Optional Fields

SKILL.md Requirements

Location: skills/skill-name/SKILL.md

Frontmatter (Required)

Copy---
name: skill-name
description: Brief description of what this skill does and when to use it.
allowed-tools: Read, Grep, Glob
---

Description Best Practices

Good (specific triggers):

Copydescription: Extract text and tables from PDF files. Use when working with PDF files, forms, or document extraction.

Bad (vague):

Copydescription: Helps with documents

Skill Content

After frontmatter, include:

• Instructions for Claude
• Examples of usage
• Reference material (or link to separate reference.md)

Command Requirements

Location: commands/command-name.md or commands/prefix/command-name.md

Frontmatter (Optional but Recommended)

Copy---
description: What this command does
argument-hint: <required-arg> [optional-arg]
allowed-tools: Read, Write, Glob
model: sonnet
---

Namespacing Commands

Use subdirectories for prefixed commands:

• commands/pb/validate.md → /pb:validate
• commands/git/commit.md → /git:commit

Using Arguments

• $ARGUMENTS - All arguments as string
• $1, $2, etc. - Positional arguments

Including External Content

• @filepath - Include file contents
• !backtickcommandbacktick`` - Execute bash command

Agent Requirements

Location: agents/agent-name.md

Frontmatter (Required)

Copy---
name: agent-name
description: When to invoke this agent and what it does.
tools: Read, Grep, Glob, Bash
model: sonnet
permissionMode: default
skills: skill1, skill2
---

Agent Content

After frontmatter, include:

• Agent's role and expertise
• Step-by-step instructions
• Checklists and procedures

Common Errors and Fixes

Error: Skill not discovered

Causes:

1. Flat file format (skills/my-skill.md) instead of directory (skills/my-skill/SKILL.md)
2. Missing or invalid YAML frontmatter
3. Description doesn't match user queries

Fixes:

1. Convert to directory format with SKILL.md
2. Validate YAML syntax (check --- delimiters)
3. Make description specific with trigger phrases

Error: Command not appearing in /help

Causes:

1. Missing .md extension
2. Invalid frontmatter YAML
3. File in wrong location

Fixes:

1. Ensure file ends with .md
2. Validate YAML with proper --- delimiters
3. Place in commands/ at plugin root

Error: Plugin not loading

Causes:

1. Invalid JSON in plugin.json
2. Missing required fields (name, description, version, author.name)
3. Directories inside .claude-plugin/ instead of plugin root

Fixes:

1. Validate JSON syntax
2. Add all required fields
3. Move directories to plugin root level

Error: Agent not invokable

Causes:

1. Missing name or description in frontmatter
2. File not in agents/ directory
3. Missing .md extension

Fixes:

1. Add required frontmatter fields
2. Place file in agents/ at plugin root
3. Ensure .md extension

Validation Checklist

Before distributing a plugin:

• .claude-plugin/plugin.json exists with required fields
• All skills use skills/name/SKILL.md format
• All skills have valid YAML frontmatter
• All commands have .md extension
• All agents have name and description
• No empty directories (agents/, commands/)
• Directories are at plugin root, not in .claude-plugin/
• README.md documents usage

See reference.md for complete JSON schemas and examples.