Package a Skill as a Plugin

You built a skill that solves a real bottleneck in your repository. It triggers consistently, follows your team's guidelines, and saves thirty minutes of manual work every morning. But when a teammate on another project asks for it, how do you share it? If your answer is "copy the folder from my .claude/skills directory into yours," you have hit the limits of local skills.

Copying folders by hand creates maintenance debt. The moment you patch a bug or improve a prompt description, your teammate's copy is instantly out of date. This is why Claude Code introduces plugins: a versioned, distributable packaging standard that lets you bundle skills, subagents, lifecycle hooks, and MCP servers into an installable package.

Why move from a standalone skill to a plugin

A local skill is a single folder. A plugin is a cohesive system. Consider packaging your skills into a plugin when:

• You have multiple related skills that belong together (for example, a database migration suite containing creation, testing, and rollback skills).
• Your workflow needs custom subagents or hooks to enforce pre-commit rules alongside the skill prompt.
• You want to distribute capabilities across multiple repositories without manually syncing git commits.
• You need version pinning so production teams can upgrade deliberately rather than having changes applied silently.

The plugin directory layout

A Claude Code plugin requires a structured layout. At the root of the repository sits the `.claude-plugin/` directory containing the required `plugin.json` manifest. Skills, agents, and hooks live in dedicated subdirectories.

Writing the plugin manifest: plugin.json

The manifest file at `.claude-plugin/plugin.json` tells Claude Code how to register your plugin and what capabilities it contains.

{
  "name": "dev-ops-toolkit",
  "version": "1.0.0",
  "description": "Automated deployment, health verification, and rollback workflows for microservices.",
  "author": {
    "name": "Platform Engineering",
    "email": "ops@example.com"
  },
  "homepage": "https://github.com/example/dev-ops-toolkit",
  "license": "MIT"
}

Use lowercase kebab-case for the plugin name. When Claude Code installs a plugin, all bundled skills are namespaced with the plugin name (`dev-ops-toolkit:deploy-staging`). This namespaces your skills automatically so they never collide with local project skills.

Testing your plugin from a local marketplace

You do not need to publish to a public registry to test a plugin. You can register any local folder on your disk as a private marketplace.

Choosing the right installation scope

When you install a plugin, Claude Code allows you to specify its scope:

• project: Saved to `.claude/settings.json`. Team members who clone the repo automatically get the plugin enabled.
• user: Saved to `~/.claude/settings.json`. Available across all projects on your local machine.
• local: Saved to `.claude/settings.local.json`. Active only in your current workspace and kept out of version control.

Reloading plugins during active development

When you edit a skill or agent inside a plugin, you do not need to restart your terminal session. Type `/reload-plugins` to clear cached manifests and reload all definitions from disk.