Plugin Structure for Claude Code

A Claude Code skill for understanding and implementing the standardized directory structure of Claude Code plugins — covering automatic component discovery, file conventions, and plugin architecture.

When to Use This Skill

Choose this skill when:

• Understanding how Claude Code discovers and loads plugin components
• Setting up the correct directory layout for a new plugin
• Adding new skills, commands, or hooks to an existing plugin
• Troubleshooting plugin loading issues
• Building plugins that follow the standard structure

Consider alternatives when:

• You need to build a single skill without a plugin (use skill creation directly)
• You need an MCP server (use the MCP builder skill)
• You need command-line tools (use standard CLI frameworks)

Quick Start

my-plugin/
├── plugin.json              # Plugin manifest (required)
├── README.md                # Plugin documentation
├── CHANGELOG.md             # Version history
├── skills/                  # Skill definitions
│   ├── code-review.md       # Auto-discovered skill
│   └── test-generator.md    # Auto-discovered skill
├── commands/                # Slash commands
│   ├── deploy.md            # /deploy command
│   └── release.md           # /release command
├── hooks/                   # Event hooks
│   └── post-write.json      # Hook configuration
└── assets/                  # Plugin assets
    └── templates/           # Template files

Core Concepts

Component Discovery

Directory	Pattern	Discovery
skills/	*.md	Auto-discovered by Claude Code
commands/	*.md	Registered as /command-name
hooks/	*.json	Event listeners registered
assets/	Any	Referenced by skills/commands

Plugin Manifest

Copy
{
  "name": "code-quality-suite",
  "version": "1.0.0",
  "description": "Comprehensive code quality tools",
  "author": "Developer",
  "repository": "https://github.com/user/code-quality-suite",
  "license": "MIT",
  "claude_version": ">=1.0.0",
  "skills": ["skills/*.md"],
  "commands": ["commands/*.md"],
  "hooks": ["hooks/*.json"],
  "dependencies": {
    "eslint": ">=8.0.0"
  },
  "settings": {
    "strictness": {
      "type": "string",
      "default": "standard",
      "enum": ["relaxed", "standard", "strict"]
    }
  }
}

Component File Formats

Copy
# skills/code-review.md
---
description: Perform a thorough code review
triggers:
  - "review code"
  - "code review"
  - "review my changes"
---

Perform a comprehensive code review:
1. Check for bugs and logic errors
2. Evaluate code style and readability
3. Identify security vulnerabilities
4. Suggest improvements

# commands/deploy.md
---
description: Deploy application to the specified environment
arguments:
  - name: environment
    description: Target environment
    required: true
    default: staging
---

Deploy to $ARGUMENTS.environment:
1. Run test suite
2. Build production bundle
3. Deploy to $ARGUMENTS.environment
4. Verify health check

Configuration

Parameter	Type	Default	Description
name	string	—	Plugin identifier (required, kebab-case)
version	string	—	Semantic version (required)
description	string	—	Short description
claude_version	string	"*"	Required Claude Code version
skills	array	["skills/*.md"]	Skill file glob patterns
commands	array	["commands/*.md"]	Command file glob patterns
hooks	array	["hooks/*.json"]	Hook config glob patterns
dependencies	object	{}	Required system tools
settings	object	{}	Plugin settings schema

Best Practices

1. Follow the standard directory layout exactly — Claude Code uses convention over configuration for component discovery; non-standard layouts prevent automatic loading.

2. Use kebab-case for plugin and file names — code-quality-suite, not codeQualitySuite; kebab-case is the convention for plugin identifiers and file names.

3. Keep the manifest minimal — only declare what your plugin actually provides; empty arrays for unused component types are cleaner than placeholder files.

4. Include a README.md with installation and usage — document how to install the plugin, what skills/commands it provides, and how to configure settings.

5. Test component discovery after changes — after adding or renaming files, verify the plugin loads correctly by running claude plugin list and testing each skill/command.

Common Issues

Plugin not recognized after installation — The plugin.json manifest is missing or has invalid JSON. Validate the JSON syntax and ensure the name field is present.

Skills not appearing in Claude Code — Check that skill files match the glob pattern in plugin.json. The default skills/*.md only matches files directly in the skills/ directory, not subdirectories.

Command arguments not substituted — Argument names in the frontmatter must match the $ARGUMENTS.name placeholders in the command body exactly (case-sensitive).