Building Claude Plugins
Extend Claude for your team
Claude plugins let you package reusable workflows, agents, and skills into a distributable unit that any Claude Code user can install. If you find yourself giving Claude the same context repeatedly, or if your team needs consistent behavior across sessions, a plugin is the answer.
What a plugin is
A Claude plugin is a directory with a defined structure that Claude Code recognizes when installed. At minimum it contains a plugin.json manifest. On top of that, you can include skills (reusable workflow instructions), agents (specialized subagents), and hooks (event-triggered automations).
Plugins live in a plugin marketplace or can be installed locally. Once installed, their skills become available as slash commands, their agents become referenceable with @, and their hooks fire automatically on configured events.
Plugin structure
my-plugin/
.claude-plugin/
plugin.json
skills/
my-skill/
SKILL.md
agents/
my-agent/
AGENT.md
hooks/
pre-commit/
HOOK.md
The key rule: skills, agents, and hooks live at the root of the plugin directory. Claude Code uses auto-discovery — it scans these directories and registers everything it finds. You do not need to declare them in plugin.json.
plugin.json
The manifest file identifies your plugin and provides metadata. Keep it minimal.
{
"name": "my-plugin",
"description": "What this plugin does",
"version": "0.1.0",
"author": { "name": "Your Name" },
"license": "MIT"
}Do not add a skills array or agents array to plugin.json. Auto-discovery handles registration. Adding explicit arrays can conflict with discovery and cause skills to not load.
Installation
Plugins can be installed from a GitHub repository using the Claude Code plugin system. Once installed, they are cached locally and available in every session.
From GitHub
Point Claude Code at a GitHub repo containing your plugin. It clones the repo to the plugin marketplace directory and registers the plugin.
Local development
For development, you can symlink or copy your plugin directory directly into the marketplace cache. Changes are picked up on the next session start or after running /reload-plugins.
Updating
Pull changes to the marketplace clone and clear the plugin cache to pick up updates. Claude Code does not auto-update installed plugins.
Common issues
Skills not loading
Check that SKILL.md has user-invocable: true in its frontmatter and that skills live at the plugin root, not in a nested subdirectory. The /reload-plugins count showing 0 is a display bug in some versions — test by actually invoking a skill.
Stale cache
Changes to the marketplace clone are not picked up until the cache is cleared. Remove the plugin cache directory and reinstall.
Agents not referenced
Agent names are prefixed with the plugin name. An agent named reviewer in my-plugin is referenced as @my-plugin:reviewer.
Need help putting this into practice?
Sprintt helps teams implement AI strategy, build product operating models, and ship faster. Reach out for a consultation.