Plugin Structure

Organize Claude Code plugin directories and validate plugin.json manifests.

2|1|Updated Apr 9, 2026

Search Tags:#claude code #manifest #plugin architecture #directory layout #mcp servers #auto-discovery

Ready to run

npx skills add https://github.com/timgranlundmarsden/claude-agent-flow --skill plugin-structure-timgranlundmarsden

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: Plugin Structure
Source: https://github.com/timgranlundmarsden/claude-agent-flow/tree/main/skills/plugin-structure
Command: npx skills add https://github.com/timgranlundmarsden/claude-agent-flow --skill plugin-structure-timgranlundmarsden

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill helps you understand and build Claude Code plugins without guessing the required layout, manifest settings, or component discovery rules.

Core Features & Use Cases

Plugin Architecture Guidance: Explains how to structure plugin roots, manifests, commands, agents, skills, hooks, and MCP server configuration.
Organization and Discovery: Shows how auto-discovery works, how to use portable plugin-root paths, and how to keep components maintainable as a plugin grows.
Use Case: Use this Skill when you need to scaffold a new plugin, reorganize an existing one, or troubleshoot why a command, agent, or skill is not loading correctly.

Quick Start

Ask Claude Code to design or review your plugin directory layout and plugin.json settings using the plugin structure rules in this Skill.

Frequently Asked Questions about Plugin Structure

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

FAQPage Schema

How do I structure a Claude Code plugin directory layout?▼

A Claude Code plugin directory layout organizes commands, agents, skills, hooks, and MCP servers into a structured root. It applies directory layout rules and portable path references to ensure proper auto-discovery and maintainable plugin architecture.

Why is my Claude Code plugin command or agent not loading correctly?▼

Claude Code plugin components fail to load when directory structure or plugin.json manifest settings contain errors. Troubleshooting involves validating the plugin.json file, checking naming conventions, and ensuring component paths align with auto-discovery rules.

What is the best way to scaffold a new Claude Code plugin?▼

Scaffolding a Claude Code plugin involves defining the plugin root, generating a valid plugin.json manifest, and configuring component directories. Applying directory layout rules and portable plugin-root paths ensures reliable component auto-discovery from the start.

How does auto-discovery work for Claude Code plugin components?▼

Auto-discovery for Claude Code plugin components works by scanning the directory layout for correctly named commands, agents, skills, and hooks. It relies on a validated plugin.json manifest and portable path references to locate and load components without manual configuration.

Do I need a plugin.json manifest to configure MCP servers in Claude Code?▼

Yes, a plugin.json manifest is required to configure MCP servers within a Claude Code plugin. The manifest validates component organization and works with the directory layout to ensure MCP servers and other components are correctly discovered and loaded.

What are the limitations of using portable paths in Claude Code plugin architecture?▼

Portable paths in Claude Code plugin architecture must strictly follow directory layout rules to function correctly. Limitations arise if naming conventions are ignored or the plugin.json manifest is misconfigured, which breaks auto-discovery and prevents components from loading.