How to Create Your First Claude Code Plugin: Manifest, Skills, and Local Testing

What plugins are for

Plugins let you extend Claude Code with custom functionality that can be shared across projects and teams. A plugin can bundle skills, agents, hooks, and MCP servers into a self-contained directory that others can install.

According to the documentation, there are two ways to add custom skills, agents, and hooks:

• Standalone (.claude/ directory): skill names look like /hello. Best for personal workflows, project-specific customizations, and quick experiments.
• Plugins (self-contained directories with skills, agents, hooks, or a .claude-plugin/plugin.json manifest): skill names look like /plugin-name:hello. Best for sharing with teammates, distributing to the community, versioned releases, and reuse across projects.

The docs suggest starting with standalone configuration in .claude/ for quick iteration, then converting to a plugin when you're ready to share.

Step 1: Create the plugin directory

Every plugin lives in its own directory containing your skills, agents, or hooks, optionally alongside a .claude-plugin/plugin.json manifest. The location doesn't matter for local testing because you'll point Claude Code at the directory with --plugin-dir:

mkdir my-first-plugin

The remaining steps run from the parent directory and reference paths like my-first-plugin/... relative to it.

Step 2: Create the plugin manifest

The manifest file at .claude-plugin/plugin.json defines your plugin's identity: its name, description, and version. Claude Code uses this metadata to display your plugin in the plugin manager.

mkdir my-first-plugin/.claude-plugin

Then create my-first-plugin/.claude-plugin/plugin.json with this content:

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

What each field does:

• name: unique identifier and skill namespace. Skills are prefixed with this (e.g., /my-first-plugin:hello).
• description: shown in the plugin manager when browsing or installing plugins.
• version: optional. If set, users only receive updates when you bump this field.
• author: optional, helpful for attribution.

Additional fields like homepage, repository, and license are covered in the plugins reference documentation.

Step 3: Add a skill

Skills live in the skills/ directory. Each skill is a folder containing a SKILL.md file. The folder name becomes the skill name, prefixed with the plugin's namespace — a hello/ folder in a plugin named my-first-plugin creates /my-first-plugin:hello.

mkdir -p my-first-plugin/skills/hello

Then create my-first-plugin/skills/hello/SKILL.md with this content:

---
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

Step 4: Test the plugin locally

Run Claude Code with the --plugin-dir flag to load your plugin:

claude --plugin-dir ./my-first-plugin

Once Claude Code starts, try the skill:

/my-first-plugin:hello

Claude responds with a greeting. You can also run /help and open the Custom commands tab to see your skill listed under the plugin namespace.

Plugin skills are always namespaced (like /my-first-plugin:hello) to prevent conflicts when multiple plugins have skills with the same name. To change the namespace prefix, update the name field in plugin.json.

Step 5: Add skill arguments

You can make a skill dynamic by accepting user input. The $ARGUMENTS placeholder captures any text the user provides after the skill name. Update SKILL.md:

---
description: Greet the user with a personalized message
---

# Hello Skill

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

Run /reload-plugins to pick up the changes. Note a quirk called out in the docs: the skills count in the reload summary covers only commands/ directories, so it can report 0 skills even though the skill you just edited reloaded. Then try it with a name:

/my-first-plugin:hello Alex

Claude will greet you by name.

Beyond local testing

The --plugin-dir flag is intended for development and testing. When you're ready to share a plugin with others, the documentation points to creating and distributing a plugin marketplace. The docs also mention that instead of passing --plugin-dir on every launch, you can keep a plugin in your skills directory and have Claude Code load it automatically, with claude plugin init available to scaffold one.

claudedetails.com is an independent publication and is not affiliated with, endorsed by, or sponsored by Anthropic. "Claude" is a trademark of Anthropic, PBC, used here for identification purposes only. Product details can change — always confirm specifics on Anthropic's own site before making decisions based on this post.