Last week I helped a colleague debug a Claude Code plugin.
He said he had clearly written a Hook, but it never ran after editing a file. He had also added a Skill, but /plugin only showed an empty shell. I asked him to send me the directory, and the problem was a classic: everything had been piled into .claude-plugin/.
That directory looks like the “core of the plugin,” but it can only hold a single plugin.json. If you put Skills, Agents, or Hooks in there, Claude Code won’t load them as components at all.
Many people building their first plugin think of it as “bundling a few commands together.” Taken apart, a plugin is more like a toolbox with standard workstations: each folder handles one kind of capability. If something is in the wrong place, the tool itself is fine, but nobody will look for it in that drawer.
