Build a plugin
Last reviewed October 24, 2026
This step builds a small, complete Claude Code plugin: one skill that drafts release notes, and one hook that tells the agent the last release tag when a session starts. Start with Claude Code even if it is not your only target. Copilot CLI loads a Claude Code plugin as it is, and the other agents' formats differ from it mostly in where the manifest goes. The next step covers them.
The layout
A plugin is a folder. The manifest goes in .claude-plugin/plugin.json, and everything else sits at the plugin root, not inside .claude-plugin/. Claude Code finds each kind of component in its default place:
skills/<name>/SKILL.mdfor skills, the same format as a skill on its own.commands/for slash commands, though the docs prefer skills in new plugins.agents/for subagents.hooks/hooks.jsonfor hooks, which are shell commands that run on the agent's events..mcp.jsonfor MCP servers and.lsp.jsonfor language servers.bin/for executables, which go on the path of the agent's shell. claude.ai and Cowork refuse a plugin that has one.
release-notes/
├── .claude-plugin/
│ └── plugin.json
├── skills/
│ └── writing-release-notes/
│ └── SKILL.md
└── hooks/
└── hooks.jsonThe manifest
Only name is required. It must be kebab-case, and it becomes the prefix of every component, so a skill in this plugin is release-notes:writing-release-notes. Add a description, a version, an author, a license and the repository anyway: they are what people read before they install (plugin manifest reference).
{
"name": "release-notes",
"description": "Drafts release notes from the git history since the last tag.",
"version": "1.0.0",
"author": { "name": "Your Name", "email": "you@example.com" },
"license": "MIT",
"repository": "https://github.com/your-name/release-tools"
}Some names are refused. A name may not start with claude-, anthropic-, anthropics- or cc-plugin-, or put "official" beside Claude or Anthropic. Pick the name with care: once people have installed the plugin, changing name breaks their installs. Change displayName instead.
✘ name: Plugin name "claude-release-notes" is reserved: it passes as one of Anthropic's own.A skill and a hook
The skill is an ordinary one, in its own folder under skills/:
---
name: writing-release-notes
description: Drafts release notes from the git history since the last tag. Use when the user asks for release notes, a changelog entry or a summary of what changed since a version.
---
1. Find the last tag with `git describe --tags --abbrev=0`.
2. Read `git log <tag>..HEAD --oneline`.
3. Group the changes under Added, Changed and Fixed. Leave out refactors and test-only commits.
4. Show the draft and ask before writing it to CHANGELOG.md.The hook runs when a session starts. Claude Code adds what it prints to the conversation, so the agent knows the last release before anyone asks. Keep hooks this short, because Claude Code's docs tell people to read every hook before they install (hooks reference).
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "echo \"Last release tag: $(git describe --tags --abbrev=0 2>/dev/null || echo none)\""
}
]
}
]
}
}A hook that needs a file from the plugin finds it through ${CLAUDE_PLUGIN_ROOT}, in quotes. A plugin that keeps state between sessions writes it to ${CLAUDE_PLUGIN_DATA}, because an update replaces the plugin folder.
Try it before you publish
Load the plugin straight from its folder for one session, with no marketplace and nothing installed:
claude --plugin-dir ./release-notesTo see what Claude Code found without starting a session, ask for the details. This is also what a careful user looks at before installing:
$ claude --plugin-dir ./release-notes plugin details release-notes
release-notes 1.0.0
Description: Drafts release notes from the git history since the last tag.
Component inventory
Skills (1) writing-release-notes
Agents (0)
Hooks (1) SessionStart
MCP servers (0)
LSP servers (0)Then check it. claude plugin validate reads the manifest, every component and every path, and --strict turns its warnings into failures, which is what you want in CI (publish a plugin):
$ claude plugin validate --strict ./release-notes
✔ Validation passedBuilding something else? See the guides to a skill and an MCP server.