{
  "id": 151763,
  "title": "Claude Code plugin structure: the minimal layout that actually loads",
  "url": "https://urgent.news/2026/08/04/claude-code-plugin-structure-the-minimal-layout-that-actually-loads",
  "topic": "tech",
  "section": "Tech",
  "published": "2026-08-04T23:25:09.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/rulestack/claude-code-plugin-structure-the-minimal-layout-that-actually-loads-33p2"
  },
  "original_language": "en",
  "account": "The minimal structure for a Claude Code plugin involves creating a directory with two key components: the plugin root and a .claude-plugin subdirectory. Inside the plugin root, the only mandatory item is a manifest file named .mcp.json. This file holds metadata such as the plugin's name, description, and version.\n\nThe .claude-plugin directory should contain exactly one file: plugin.json. This manifest file is essential as it provides additional information for the plugin manager, such as a stable name, description, and version field. It's important to note that all other directories like skills/, agents/, hooks/, and commands/ must be placed at the plugin root level and not inside the .claude-plugin directory.\n\nIf your plugin contains only a single skill, you can simplify the structure by placing a SKILL.md file directly at the plugin root. This file serves as the sole skill and can be invoked using the frontmatter name field. When your plugin grows beyond a single skill, you can organize skills into separate directories within the skills/ folder.\n\nClaude Code plugins are not restricted to a single layout; they can grow as needed. When developing a plugin, you can test it using the claude --plugin-dir flag or create a persistent local plugin by running claude plugin init <plugin-name>. This command scaffolds a new plugin directory with a manifest and starter files. Remember, if you distribute your plugin via git, you must explicitly set the version field in plugin.json to avoid frequent updates due to minor changes.\n\nIn summary, the key points to remember are:\n1. Place all directories (skills/, agents/, hooks/, commands/) at the plugin root level.\n2. Only plugin.json should reside inside the .claude-plugin directory.\n3. For a single-skill plugin, you can use a SKILL.md file at the root.\n4. Set the version field in plugin.json when distributing via git to maintain consistent releases.",
  "summary": "You wrote a skill, it works in ~/.claude/skills/ , and now you want to hand it to a teammate — so you wrap it in a plugin. You create the folder, add a manifest, restart Claude Code… and nothing loads. No error that helps, no skill in the list. Nine times out of ten the cause is one wrong assumption about the directory layout. This post is the minimal structure that actually loads, verified…",
  "key_points": [
    "Minimal Claude Code plugin structure includes plugin root and .claude-plugin subdirectory",
    ".claude-plugin directory contains only plugin.json manifest file",
    "SKILL.md file can serve as sole skill for single-skill plugin"
  ],
  "editors_take": "The clarified plugin structure gives developers a flexible yet organized framework for building and distributing Claude Code plugins, with clear guidelines for directory layout and metadata management.",
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}