skills.rest
quanngynx
quanngynxCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

Plugin Structure

Explain Claude Code plugin directory structure and discovery rules.

Updated Mar 27, 2026
Search Tags:#claude code#skill discovery#plugin architecture#directory layout#plugin.json#auto-discovery#portable paths
One-click install
npx skills add https://github.com/quanngynx/GDGO-2026.Servexa-Warranty-AI --skill plugin-structure-quanngynx
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: Plugin Structure
Source: https://github.com/quanngynx/GDGO-2026.Servexa-Warranty-AI/tree/main/servexa-warranty-ai/.cursor/skills/plugin-structure
Command: npx skills add https://github.com/quanngynx/GDGO-2026.Servexa-Warranty-AI --skill plugin-structure-quanngynx

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

It solves confusion about how Claude Code plugins and skills must be laid out so they are auto-discovered and work correctly.

Core Features & Use Cases

  • Directory layout guidance: Ensures plugins follow the expected structure for discovery (commands, agents, skills, hooks, MCP).
  • Manifest-driven configuration: Explains how .claude-plugin/plugin.json defines metadata and optional custom component paths.
  • Portable path references: Shows how to use ${CLAUDE_PLUGIN_ROOT} to keep scripts and hooks reliable across installations.
  • Skill-specific entrypoint: Clarifies that each skill subdirectory must contain a root SKILL.md with required YAML frontmatter for discovery.

Quick Start

Tell the AI: “Help me scaffold a Claude Code plugin named servexa-warranty-ai with a skills/ section, and generate the correct SKILL.md template using ${CLAUDE_PLUGIN_ROOT} for any script paths.”

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 for auto-discovery?▼

To structure a Claude Code plugin for auto-discovery, you must place the manifest at `.claude-plugin/plugin.json` and organize commands, agents, skills, hooks, and MCP servers into their expected root directories. This layout ensures the platform correctly detects and loads your components.

Why does my Claude Code skill not show up during plugin discovery?▼

Your Claude Code skill is not discovered because its subdirectory lacks a root `SKILL.md` file with required YAML frontmatter containing `name` and `description` fields. Additionally, directory names must use kebab-case conventions for successful auto-discovery.

What is the correct directory layout for Claude Code plugin components?▼

The correct directory layout for Claude Code plugin components separates commands, agents, skills, hooks, and MCP servers into distinct root folders. This structure is governed by the `.claude-plugin/plugin.json` manifest, which defines metadata and optional custom component paths.

How do I use ${CLAUDE_PLUGIN_ROOT} for portable paths in Claude Code hooks?▼

You use `${CLAUDE_PLUGIN_ROOT}` in Claude Code hooks and scripts to construct portable paths, ensuring intra-plugin references remain reliable across different installations. This variable prevents directory resolution errors when the plugin is deployed.

Can I customize the directory paths for Claude Code plugin commands and agents?▼

Yes, you can customize directory paths for Claude Code plugin commands and agents by defining optional custom component paths within the `.claude-plugin/plugin.json` manifest. This allows teams to adapt the plugin architecture to maintainable extension workflows.

Related Skills

Explore More Software Engineering Skills→
Fr-e-dFr-e-d
157

architecture-extract

Analyze project directory structures to generate architectural summaries.

Community
Basic
gonzalezpazmonicagonzalezpazmonica
47

plugin-packaging

Package and validate PM-Workspace as a Claude Code plugin with a generated manifest.

Community
Intermediate
hajrasarwar11hajrasarwar11

skill-authoring

Create reusable skills with SKILL.md frontmatter and optional directories.

Community
Intermediate
vanman2024vanman2024
3

MCP Development

Scaffold and validate FastMCP MCP server structures with scripts.

Community
Intermediate