Skip to content

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.md for 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.json for hooks, which are shell commands that run on the agent's events.
  • .mcp.json for MCP servers and .lsp.json for 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.
layout
release-notes/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── writing-release-notes/
│       └── SKILL.md
└── hooks/
    └── hooks.json

The 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).

.claude-plugin/plugin.json
{
  "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.

claude plugin validate
✘ 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/:

skills/writing-release-notes/SKILL.md
---
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/hooks.json
{
  "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:

shell
claude --plugin-dir ./release-notes

To see what Claude Code found without starting a session, ask for the details. This is also what a careful user looks at before installing:

shell (shortened)
$ 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):

shell
$ claude plugin validate --strict ./release-notes
✔ Validation passed

Building something else? See the guides to a skill and an MCP server.