Guide

Create a minimal Claude Code plugin (tested)

One command scaffolds a working local plugin. What init creates, how the SKILL.md frontmatter works, and when to package.

By Arun BabuOctober 10, 2026Beginner

You do not need a repository or a marketplace to make a Claude Code plugin. One command scaffolds a working local one. Tested on Claude Code v2.1.296 (October 2026); real output below.

The one command

claude plugin init test-mini-plugin

Real output:

✔ Created plugin "test-mini-plugin" at ~/.claude/skills/test-mini-plugin It will auto-load next session as test-mini-plugin@skills-dir. Run /reload-plugins to load it now.

That is a complete, loadable plugin. claude plugin list shows it under "Skills-directory plugins (.claude/skills/*)" with version 0.1.0 and status loaded.

What the scaffold contains

The whole plugin is one directory with one file, SKILL.md. The generated frontmatter:

name: test-mini-plugin description: TODO - describe WHEN Claude should use this. Include trigger phrases users might say ("do X", "set up Y", "review Z"). Be specific; this string is what Claude matches the user's request against.

The template's own instruction is the important part: the description string is how Claude decides to use your plugin. Write it as trigger phrases a user would actually say, not a marketing line. The body below the frontmatter is the procedure Claude follows - what the skill does and the steps to take.

Working with it

Load it now: /reload-plugins in a running session (otherwise it auto-loads next session).
Disable without deleting: claude plugin disable test-mini-plugin@skills-dir
Remove entirely: delete the directory. There is no uninstall command for skills-dir plugins.
Edit and iterate: SKILL.md is plain text; changes take effect on reload.

Because the plugin lives in ~/.claude/skills/, it is machine-local and user-scoped. To share one with a team, move the directory into a project's .claude/ or package it into a marketplace repo. Scope choices are covered in user, project or local.

When one skill is not enough

The init scaffold is a skills-only plugin. A full package adds a .claude-plugin/plugin.json manifest and can bundle commands, sub-agents, hooks and MCP servers alongside skills - the structure is in Anthropic's plugins reference, and our build-a-plugin guide walks the components.

Two shortcuts worth knowing:

Plugin Create is Anthropic's official meta-plugin: it helps you build custom plugins from inside Claude by describing the workflow. It is on our official plugins page.
The official knowledge-work-plugins repository is the best reference material: every package in it is public, so you can copy the shape of a real one. Installing from it is covered in install from a marketplace.

Start with init, prove the procedure on real tasks, then package.