plugin-sdk-patterns

Building a Claude Code plugin that loads

Plugins fail quietly. A manifest in the wrong folder, a frontmatter key the loader does not read, or a hook that exits 1 leaves every file looking right while the component does nothing. For a skill that exists on disk but did not register, the loader answers Unknown skill: <plugin>:<name>, the same string it gives for a typo. This file holds the facts that decide whether each part of a plugin loads and behaves as written.

Done means claude plugin list shows the plugin loaded with no error, and every component you touched did its job once in a real session (section 7).

If the repo you are working in has its own plugin standard, that standard wins where it differs from this file. In the Magus marketplace source repo, also read section 8.

1. Directory structure

my-plugin/
├── .claude-plugin/
│   └── plugin.json        # the manifest; the only file that belongs in this folder
├── skills/
│   └── <skill-name>/
│       ├── SKILL.md
│       └── references/    # optional depth, opened only on an explicit instruction
├── commands/
│   └── <command>.md
├── agents/
│   └── <agent>.md
├── hooks/
│   └── hooks.json
├── .mcp.json              # MCP servers, if the plugin ships any
└── README.md              # for people; nothing loads it

• The manifest lives at .claude-plugin/plugin.json. A plugin.json at the plugin root is consulted at install time only; the runtime loader never reads it. The skills, dependencies and mcpServers it declares do nothing, the plugin falls back to scanning its default folders, and every nested skill it lists answers Unknown skill.
• Only plugin.json goes inside .claude-plugin/. Every component folder sits at the plugin root.
• Folders the loader does not know, such as mcp-servers/ or examples/, are never read.
• A plugin cannot reach outside its own directory. A ../shared component path is rejected, and files above the plugin root are not copied into the install cache, so a script that reads them works in your checkout and fails once installed.
• Component paths are relative to the plugin root, start with ./, and use forward slashes.