Building Claude Plugins.
Conventions over configuration.
Plugins are how you encode your team's way of working and carry it across projects. They are also simpler than most documentation makes them look: directories with conventions, discovered automatically, shared via GitHub. Here is what you actually need to know.
Ricardo Ramirez
Founder, Sprintt · Product Builder
TL;DR · 4 takeaways
- 01
Skills, agents, and hooks live at the plugin root.
- 02
plugin.json is minimal. Do not declare what auto-discovery finds.
- 03
Distribute by GitHub. Updates require cache clears.
- 04
Agents and skills are namespaced by plugin name.
What a plugin is.
A plugin is a directory containing some combination of skills, agents, and hooks, with a minimal manifest at the root. Claude Code auto-discovers everything at the plugin root. You do not declare what is inside, the tool finds it.
Conventions over configuration. If you are editing plugin.json to list your skills, you are fighting the tool.
That model is why good plugins stay small. One plugin per concern, composed together in a project, rather than one monolith that tries to own everything.
Directory structure.
The canonical shape. Skills, agents, and hooks live at the plugin root, not in nested folders. This is the most common place people trip.
my-plugin/
├── plugin.json
├── skills/
│ ├── push/SKILL.md
│ └── pr/SKILL.md
├── agents/
│ └── reviewer/AGENT.md
└── hooks/
└── pre-commit/HOOK.mdplugin.json, kept minimal.
Keep this file boring. The more you add, the more you fight auto-discovery.
{
"name": "my-plugin",
"description": "What this plugin does, in one sentence.",
"version": "0.1.0",
"author": { "name": "Your Name" },
"license": "MIT"
}Do not add a skills array. Do not add an agents array. Auto-discovery handles registration. Declaring explicitly conflicts with discovery and causes skills to silently fail to load. This is the top-reported plugin bug, and it is almost always a manifest that is trying to do too much.
Installation and sharing.
- 01
From GitHub
Point Claude Code at a GitHub repo containing your plugin. It clones into the local plugin cache and registers on the next session.
- 02
Local development
Symlink or copy your plugin directory directly into the cache. Run /reload-plugins or start a new session to pick up changes.
- 03
Updating
Pull changes and clear the plugin cache. Claude Code does not auto-update installed plugins, by design, to avoid surprises.
- 04
Namespacing
Agents and skills are prefixed with the plugin name. An agent called reviewer inside my-plugin is invoked as @my-plugin:reviewer.
Common issues.
- 01
Skills are not loading
Check SKILL.md has user-invocable: true in frontmatter and lives at the plugin root, not in a nested subdirectory. Test by invoking a skill rather than trusting the reload count.
- 02
Stale cache
Marketplace clone changes are not picked up until the cache is cleared. Remove the plugin cache directory and reinstall.
- 03
Agents not referenced
Agent names are prefixed by plugin name. Use @plugin-name:agent-name, not just @agent-name.
- 04
Hook not firing
Check HOOK.md has the correct event in frontmatter (pre-commit, post-task, etc.) and that the hook script is executable if it shells out.
Plugins worth stealing.
Patterns I have shipped across client projects that are worth starting from:
- 01
A dev-workflow plugin
Skills for push, pr, check, new-feature. Agents for reviewer, security, qa. One plugin covers the daily surface of engineering work.
- 02
A brand plugin
Hooks that load your design tokens. A skill that scaffolds a new component in your house style. Saves the "does this look right" back-and-forth.
- 03
A compliance plugin
Hooks that block committing secrets. Skills that produce SOC2-ready audit notes. Guardrails, automated.
- 04
A content plugin
Skills for drafting LinkedIn posts, blog posts, newsletters in your voice. Your voice, encoded, reusable.
If this was useful, pass it on.
Ricardo Ramirez
Product Builder and Founder of Sprintt. Advising product teams on AI strategy and operating models.