Create plugins ↗

    mkdir my-first-plugin
    ```
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Create the plugin manifest"></span>
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.

Create the `.claude-plugin` directory inside your plugin folder:

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

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

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

| Field         | Purpose                                                                                                |
| :------------ | :----------------------------------------------------------------------------------------------------- |
| `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`     | Track releases using [semantic versioning](/en/plugins-reference#version-management).                  |
| `author`      | Optional. Helpful for attribution.                                                                     |

For additional fields like `homepage`, `repository`, and `license`, see the [full manifest schema](/en/plugins-reference#plugin-manifest-schema).
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Add a skill"></span>
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 (`hello/` in a plugin named `my-first-plugin` creates `/my-first-plugin:hello`).

Create a skill directory in your plugin folder:

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

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

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

    Greet the user warmly and ask how you can help them today.
    ```
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Test your plugin"></span>
Run Claude Code with the `--plugin-dir` flag to load your plugin:

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

Once Claude Code starts, try your new skill:

```shell
    /my-first-plugin:hello
    ```

You'll see Claude respond with a greeting. Run `/help` to see your skill listed under the plugin namespace.

<span class="callout-start" data-callout-type="note"></span>
  **Why namespacing?** Plugin skills are always namespaced (like `/greet: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`.
<span class="callout-end"></span>
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Add skill arguments"></span>
Make your skill dynamic by accepting user input. The `$ARGUMENTS` placeholder captures any text the user provides after the skill name.

Update your `SKILL.md` file:

```markdown
    ---
    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.
    ```

Restart Claude Code to pick up the changes, then try the skill with your name:

```shell
    /my-first-plugin:hello Alex
    ```

Claude will greet you by name. For more on passing arguments to skills, see [Skills](/en/skills#pass-arguments-to-skills).
  <span class="step-end"></span>
<span class="steps-end"></span>

You've successfully created and tested a plugin with these key components:

* **Plugin manifest** (`.claude-plugin/plugin.json`): describes your plugin's metadata
* **Skills directory** (`skills/`): contains your custom skills
* **Skill arguments** (`$ARGUMENTS`): captures user input for dynamic behavior

<span class="callout-start" data-callout-type="tip"></span>
  The `--plugin-dir` flag is useful for development and testing. When you're ready to share your plugin with others, see [Create and distribute a plugin marketplace](/en/plugin-marketplaces).
<span class="callout-end"></span>

## Plugin structure overview

You've created a plugin with a skill, but plugins can include much more: custom agents, hooks, MCP servers, and LSP servers.

<span class="callout-start" data-callout-type="warning"></span>
  **Common mistake**: Don't put `commands/`, `agents/`, `skills/`, or `hooks/` inside the `.claude-plugin/` directory. Only `plugin.json` goes inside `.claude-plugin/`. All other directories must be at the plugin root level.
<span class="callout-end"></span>

| Directory         | Location    | Purpose                                                                        |
| :---------------- | :---------- | :----------------------------------------------------------------------------- |
| `.claude-plugin/` | Plugin root | Contains `plugin.json` manifest (optional if components use default locations) |
| `commands/`       | Plugin root | Skills as Markdown files                                                       |
| `agents/`         | Plugin root | Custom agent definitions                                                       |
| `skills/`         | Plugin root | Agent Skills with `SKILL.md` files                                             |
| `hooks/`          | Plugin root | Event handlers in `hooks.json`                                                 |
| `.mcp.json`       | Plugin root | MCP server configurations                                                      |
| `.lsp.json`       | Plugin root | LSP server configurations for code intelligence                                |
| `settings.json`   | Plugin root | Default [settings](/en/settings) applied when the plugin is enabled            |

<span class="callout-start" data-callout-type="note"></span>
  **Next steps**: Ready to add more features? Jump to [Develop more complex plugins](#develop-more-complex-plugins) to add agents, hooks, MCP servers, and LSP servers. For complete technical specifications of all plugin components, see [Plugins reference](/en/plugins-reference).
<span class="callout-end"></span>

## Develop more complex plugins

Once you're comfortable with basic plugins, you can create more sophisticated extensions.

### Add Skills to your plugin

Plugins can include [Agent Skills](/en/skills) to extend Claude's capabilities. Skills are model-invoked: Claude automatically uses them based on the task context.

Add a `skills/` directory at your plugin root with Skill folders containing `SKILL.md` files:

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

---
name: code-review
description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
---

When reviewing code, check for:
1. Code organization and structure
2. Error handling
3. Security concerns
4. Test coverage

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

{
  "agent": "security-reviewer"
}

claude --plugin-dir ./my-plugin

claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

    mkdir -p my-plugin/.claude-plugin
    ```

Create the manifest file at `my-plugin/.claude-plugin/plugin.json`:

```json
    {
      "name": "my-plugin",
      "description": "Migrated from standalone configuration",
      "version": "1.0.0"
    }
    ```
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Copy your existing files"></span>
Copy your existing configurations to the plugin directory:

```bash
    # Copy commands
    cp -r .claude/commands my-plugin/

    # Copy agents (if any)
    cp -r .claude/agents my-plugin/

    # Copy skills (if any)
    cp -r .claude/skills my-plugin/
    ```
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Migrate hooks"></span>
If you have hooks in your settings, create a hooks directory:

```bash
    mkdir my-plugin/hooks
    ```

Create `my-plugin/hooks/hooks.json` with your hooks configuration. Copy the `hooks` object from your `.claude/settings.json` or `settings.local.json`, since the format is the same. The command receives hook input as JSON on stdin, so use `jq` to extract the file path:

```json
    {
      "hooks": {
        "PostToolUse": [
          {
            "matcher": "Write|Edit",
            "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]
          }
        ]
      }
    }
    ```
  <span class="step-end"></span>

  <span class="step-marker" data-step-title="Test your migrated plugin"></span>
Load your plugin to verify everything works:

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

Test each component: run your commands, check agents appear in `/agents`, and verify hooks trigger correctly.
  <span class="step-end"></span>
<span class="steps-end"></span>

### What changes when migrating

| Standalone (`.claude/`)       | Plugin                           |
| :---------------------------- | :------------------------------- |
| Only available in one project | Can be shared via marketplaces   |
| Files in `.claude/commands/`  | Files in `plugin-name/commands/` |
| Hooks in `settings.json`      | Hooks in `hooks/hooks.json`      |
| Must manually copy to share   | Install with `/plugin install`   |

<span class="callout-start" data-callout-type="note"></span>
  After migrating, you can remove the original files from `.claude/` to avoid duplicates. The plugin version will take precedence when loaded.
<span class="callout-end"></span>

## Next steps

Now that you understand Claude Code's plugin system, here are suggested paths for different goals:

### For plugin users

* [Discover and install plugins](/en/discover-plugins): browse marketplaces and install plugins
* [Configure team marketplaces](/en/discover-plugins#configure-team-marketplaces): set up repository-level plugins for your team

### For plugin developers

* [Create and distribute a marketplace](/en/plugin-marketplaces): package and share your plugins
* [Plugins reference](/en/plugins-reference): complete technical specifications
* Dive deeper into specific plugin components:
  * [Skills](/en/skills): skill development details
  * [Subagents](/en/sub-agents): agent configuration and capabilities
  * [Hooks](/en/hooks): event handling and automation
  * [MCP](/en/mcp): external tool integration