Why You Should Move From Skills to Plugins in Claude Code

Claude Code’s plugin system solves the problem of scattered .claude/ configuration by packaging settings, skills, agents, hooks, and MCP servers into standard, versioned units that are easy to share, audit, and distribute.

Independent configuration vs. plugins

Independent configuration ( .claude/ directory) uses paths like /hello and is ideal for personal workflows, project‑specific customization, and rapid experimentation.

Plugins are self‑contained directories with a manifest; they are invoked as /plugin-name:hello and are suited for team sharing, community distribution, versioned releases, and cross‑project reuse.

Recommendation: start with independent configuration for quick iteration, then convert to a plugin when you need to share.

Quick start: building your first plugin

Create the plugin directory and a manifest file:

mkdir my-first-plugin
mkdir my-first-plugin/.claude-plugin

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

Add a skill under skills/:

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

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

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

Test locally: claude --plugin-dir ./my-first-plugin Invoke with /my-first-plugin:hello. The namespace prevents name collisions; arguments can be passed using the $ARGUMENTS placeholder in SKILL.md.

Common mistake

Do not place commands/, agents/, or skills/ inside .claude-plugin/. Only plugin.json belongs there; all other directories should be at the plugin root. Single‑skill plugins may keep SKILL.md at the root with a name field, while multi‑skill plugins use the skills/ folder.

What a plugin can contain

.claude-plugin/

: only

plugin.json

skills/

: skill folders with

<name>/SKILL.md

commands/

: legacy flat markdown files (new plugins should use skills/) agents/: custom agent definitions hooks/: event handlers, defined in

hooks.json

monitors/

: background monitor definitions, e.g.:

[
  {"name": "error-log", "command": "tail -F ./logs/error.log", "description": "Application error log"}
]

.lsp.json

: language‑server configuration, e.g.:

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {".go": "go"}
  }
}

.mcp.json

: MCP server configuration bin/: executables added to PATH when the plugin is enabled settings.json: default settings (currently supports agent and subagentStatusLine)

{"agent": "security-reviewer"}

Testing plugins

Use the --plugin-dir flag to point to a directory or a .zip archive: claude --plugin-dir ./my-plugin.zip Local plugins with the same name as marketplace plugins take precedence in the current session. The flag cannot override plugins that are forced‑enabled or disabled. Remote testing uses --plugin-url:

claude --plugin-url https://example.com/my-plugin.zip

If loading fails, errors appear in the /plugin manager’s Errors tab. Hot‑reload updates with /reload-plugins. Debugging steps: verify directory placement, test components individually, and use the CLI debugging tools referenced in the official Plugins documentation.

Submitting to the community marketplace

claude-plugins-official : curated set automatically registered on first interactive launch.

claude-community : third‑party market; add with /plugin marketplace add anthropics/claude-plugins-community.

Validate locally before submission: claude plugin validate ./your-plugin Successful validation prints ✔ Validation passed; use --strict to treat warnings as errors.

Submission requires a Claude.ai form (Team/Enterprise) or the Console form for individuals. After approval, the plugin is pinned to a specific commit SHA; subsequent pushes trigger CI to update the pin. The official market follows a separate selection process.

Migrating from .claude/ to a plugin

Copy existing configuration files into the plugin structure:

cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/
cp -r .claude/skills my-plugin/

Move hook definitions from settings.json to hooks/hooks.json. Delete the original .claude/ files. Project‑level and user‑level .claude/agents/ override same‑named plugin agents; skill names are namespaced, so they coexist without conflict.

What plugins actually change

Plugins do not introduce new capabilities; they simply standardize existing skills, agents, hooks, and MCP servers, adding versioning, naming, description, and distribution channels. This turns Claude Code from a standalone tool into a platform where a marketplace can grow, ending the era of manually copying .claude/ directories. Other AI tools such as Cursor and dsh are also launching plugin markets, indicating a broader move toward standardized AI‑native software.

Reference: https://mp.weixin.qq.com/s?__biz=MzA5MTIxNTY4MQ==∣=2461160757&idx=1&sn=180b24d11c0c1135f25870338789a917&scene=21