# Claude Code Plugins and skills

> How Claude Code plugins package skills, agents, hooks, MCP, LSP and monitors, and how to migrate standalone configuration into reusable plugins.

URL: https://docs.passion8.cc/en/docs/claude-code/plugins
Language: en
Publisher: Passion8

Claude Code offers two extension layers. If you are choosing between `CLAUDE.md`, a skill, subagent, MCP, hook or plugin, start with [how it works and the extension map](https://docs.passion8.cc/en/docs/claude-code/how-it-works). For official, community and internal marketplaces, version constraints, recommendations and security governance, see [plugin marketplaces and distribution](https://docs.passion8.cc/en/docs/claude-code/plugin-marketplaces).

| Method | Location | Suitable for |
| --- | --- | --- |
| Standalone configuration | Project or user `.claude/` | One project, personal workflows and quick experiments |
| Plugin | Independent directory, optionally with `.claude-plugin/plugin.json` | Team sharing, versioning, multiple projects and marketplace distribution |

For a command needed only in this project, begin with `.claude/commands` or `.claude/skills`. Package it as a plugin when it needs to be shared or reused.

## What a plugin can contain

| Directory or file | Purpose |
| --- | --- |
| `.claude-plugin/plugin.json` | Manifest with name, description and version |
| `skills/` | Skill directories, each containing `SKILL.md` |
| `commands/` | Legacy flat commands; prefer `skills/` in new plugins |
| `agents/` | Custom subagents |
| `hooks/` or `hooks.json` | Event handlers |
| `.mcp.json` | MCP server configuration |
| `.lsp.json` | Language server configuration |
| `monitors/` | Background monitor configuration |
| `bin/` | Executables added to Bash PATH when the plugin is enabled |
| `settings.json` | Default plugin settings |




Do not put `skills/`, `agents/` or `hooks/` inside `.claude-plugin/`. That directory contains only `plugin.json`.




## Minimal plugin structure

```text
my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── review-api/
        └── SKILL.md
```

`plugin.json`:

```json
{
  "name": "my-plugin",
  "description": "Team workflows for API review",
  "version": "1.0.0",
  "author": {
    "name": "Your Team"
  }
}
```

`skills/review-api/SKILL.md`:

```markdown
---
description: Review API changes for compatibility, auth, pagination, errors, and observability.
---

Review the API change in $ARGUMENTS.
Check request/response compatibility, auth boundary, pagination, error codes, and logs.
Return findings first, then suggested fixes.
```

Enable it for testing:

```bash
claude --plugin-dir ./my-plugin
```

Invoke it in the session:

```text
/my-plugin:review-api src/routes/billing.ts
```

## Skill names and arguments

| Item | Meaning |
| --- | --- |
| Standalone skill | Usually `/skill-name` |
| Plugin skill | Usually `/plugin-name:skill-name` |
| Arguments | `$ARGUMENTS` receives text after the command |
| Automatic invocation | `description` helps Claude decide when to use it |
| Disable automatic invocation | Set `disable-model-invocation: true` in frontmatter |
| Restrict tools | Use `allowed-tools` or permission rules |

Namespaces prevent collisions when several plugins define commands such as `/deploy` or `/review`.

## When to migrate from `.claude/`

| Signal | Action |
| --- | --- |
| Several projects copy the same commands | Package a plugin |
| Teams need consistent hooks/agents | Package and version a plugin |
| Bash PATH needs helper scripts | Use plugin `bin/` |
| MCP, LSP or monitors need distribution | Manage them through the plugin manifest |
| Rules apply only to this repository | Keep project `.claude/` configuration |

A practical progression is standalone configuration, then a stable plugin, then marketplace or internal-repository distribution.

## Plugins and caching

| Operation | Cache effect |
| --- | --- |
| Invoke a skill | Appends a message; the previous prefix usually remains reusable |
| Enable a plugin containing only skills/hooks/agents | Usually appends instructions rather than rebuilding the system prompt |
| Plugin includes MCP servers | Depends on tool search; upfront schemas can invalidate the prefix |
| `/reload-plugins` | Changes affect the first turn after reload |
| Disable and re-enable | Earlier caches may remain usable within TTL |

With many plugins, check whether MCP tools are deferred. Otherwise changing the toolset can cause a cache miss.

## Official references

- [Create plugins](https://code.claude.com/docs/en/plugins.md)
- [Plugins reference](https://code.claude.com/docs/en/plugins-reference.md)
- [Extend Claude with skills](https://code.claude.com/docs/en/skills.md)
- [How Claude Code uses prompt caching](https://code.claude.com/docs/en/prompt-caching.md)