One read of Claude Documentationclaude-docs-20260925T180706Z

plugins/create-with-claude New page · 112 lines, new page

# Create a plugin with Claude ## Create the plugin with Claude's help ### Start from the Add menu ### Describe and save the plugin ### Review what Claude made ## Use, disable, or remove your plugin ## Submit a plugin you created with Claude ## Next steps

A whole new page. There's nothing to diff it against, so here is what it says.

# Create a plugin with Claude

> Make a plugin for your own workflow from claude.ai or the desktop app without writing files: choose Create with Claude and answer Claude's questions.

A [plugin](/docs/plugins/overview) packages skills, commands, and connectors. You can make one for yourself in claude.ai or the Claude desktop app without writing files: from [**Customize > Plugins**](https://claude.ai/customize/plugins), select **Add > Create with Claude**, describe what you need, and save the plugin Claude produces to your account.

A plugin you create this way is for you. It lives on your account, and on a Team or Enterprise plan you can [share it](/docs/plugins/share) with specific people or your whole organization from its page in Customize. It isn't a directory listing; if you later want that, see [Submit a plugin you created with Claude](#submit-a-plugin-you-created-with-claude) at the end of this page.

<Note>
  * If you'd rather write the files yourself, see [Plugin structure and testing](/docs/plugins/build)
  * If you want to make a plugin available to everyone in your organization, see [Publish a plugin to your organization](/docs/plugins/share#publish-a-plugin-to-your-organization)
</Note>

To begin, [start a new plugin from the Add menu](#start-from-the-add-menu), [describe it to Claude and save it](#describe-and-save-the-plugin), then [review the plugin Claude made](#review-what-claude-made).

## Create the plugin with Claude's help

When you create a plugin with Claude, you start a conversation from the **Add** menu on [**Customize > Plugins**](https://claude.ai/customize/plugins), describe the task you want the plugin to handle, and save the plugin that Claude produces.

### Start from the Add menu

To start a new plugin:

<Steps>
  <Step title="Open the Add menu">
    Go to [**Customize > Plugins**](https://claude.ai/customize/plugins) in claude.ai or the desktop app and select **Add**.
  </Step>

  <Step title="Choose how to create it">
    Choose one of these:

    * **Create with Claude**: start a new conversation, or a new Cowork task in the desktop app, with a request to create a plugin already filled in for you to send. Choose this when you can describe the task you want the plugin to handle but don't want to write skill files
    * **Create a plugin**: fill in a form with the plugin's name and what it helps with, then write its skills, commands, and connectors in an editor. Choose this when you already know what each piece should say
  </Step>
</Steps>

If neither item appears in the **Add** menu, plugin creation isn't available on your account. Your organization can turn it off, and so can your IT department's configuration of the desktop app. [Manage plugins for your organization](/docs/plugins/admin#control-what-members-add-themselves) covers the organization setting.

### Describe and save the plugin

After you choose **Create with Claude**, a conversation opens where you tell Claude what the plugin is for, and Claude assembles it as a `.plugin` file that you save to your account:

<Steps>
  <Step title="Describe what the plugin is for">
    Tell Claude the job the plugin should help with, in the same words you'd use to explain it to a colleague: the task, when it comes up, and what a good result looks like.
  </Step>

  <Step title="Answer Claude's questions">
    Answer Claude's follow-up questions, such as which of your connectors the plugin should use. You can change any of it later.
  </Step>

  <Step title="Save the plugin Claude assembles">
    Claude writes the skills and commands, includes the connectors you chose, and shows the result as a file card in the conversation. Select **Save plugin** on that card to add it to your account. It's then listed under **Customize > Plugins**, on the **Yours** view.
  </Step>
</Steps>

### Review what Claude made

Check the plugin before you rely on it:

<Steps>
  <Step title="Open the plugin">
    Open **Customize > Plugins** and select the new plugin.
  </Step>

  <Step title="Read what it contains">
    Read the skills, commands, and connectors it contains.
  </Step>

  <Step title="Sign in to its connectors">
    Sign in to any bundled connector from the plugin's page.
  </Step>

  <Step title="Try it on a real request">
    Start a chat, or a Cowork task in the desktop app, with the kind of request the plugin is for, and check that Claude follows the plugin's skills.
  </Step>
</Steps>

## Use, disable, or remove your plugin

The plugin is on your account for the organization you created it in, so it's available in your chats, in Cowork, and in Claude Code as a synced plugin.

Open the plugin from **Customize > Plugins** to disable or remove it:

* **Disable it**: turn off the plugin's toggle
* **Remove it**: open its menu and select **Remove** to delete it from your account

To give the plugin to other people in your organization, see [Share a plugin with teammates](/docs/plugins/share). It covers sharing with specific people and publishing to your organization's library, both on Team and Enterprise plans.

## Submit a plugin you created with Claude

Anthropic's directory reads plugins from a GitHub repository, so a plugin that lives only on your account can't be submitted as it is. If you decide you want it listed, get its files from the same conversation and go through the normal submission route:

<Steps>
  <Step title="Ask Claude for the plugin as a folder">
    In the conversation where Claude made the plugin, ask for it "as a plugin folder I can push to GitHub for the directory", download the zip Claude produces, and check that it has `.claude-plugin/plugin.json`, the `skills/` folder, a `README.md`, and a `LICENSE`.
  </Step>

  <Step title="Check the manifest and README">
    Unzip the folder and compare `plugin.json` with [Write the manifest](/docs/plugins/build#write-the-manifest). Claude may include fields the manifest doesn't use and leaves placeholders such as your name for you to fill in. If you have Claude Code installed, run `claude plugin validate` on the folder, as [Check the plugin on your machine](/docs/plugins/pre-submission-checklist#check-the-plugin-on-your-machine-optional) describes.
  </Step>

  <Step title="Push and submit">
    Push the folder to a public GitHub repository, then follow [Submit a plugin](/docs/plugins/submit).
  </Step>
</Steps>

## Next steps

* [Plugins](/docs/plugins/overview#manage-installed-plugins): turn off, remove, or update plugins on your account
* [Plugin feature support across platforms](/docs/plugins/platform-support): check which of the plugin's components work in chat, Cowork, and Claude Code
* [Share a plugin with teammates](/docs/plugins/share): give the plugin to specific people or your organization

plugins/org-rollout New page · 101 lines, new page

# Roll out a plugin to your whole organization ## Choose a rollout route ## Roll out through both routes ### If a developer has the plugin from both routes ## Build one repository for both audiences ## Update a plugin you've rolled out ### Update through organization settings ### Update through managed settings ## Next steps

A whole new page. There's nothing to diff it against, so here is what it says.

# Roll out a plugin to your whole organization

> Get your organization's plugin to members in claude.ai and Cowork and to developers in Claude Code by using organization settings and managed settings together.

You can get your organization's own plugin to every member two ways, and each reaches different people:

* **Organization settings on claude.ai**: members get the plugin on their accounts, where chat and Cowork use it. Plugins you add this way stay private to your organization
* **Claude Code managed settings**: Claude Code installs the plugin on developers' machines

This page is for the person rolling out a plugin their organization built, on a Team or Enterprise plan.

<Note>
  * If you want to list a plugin publicly, see [Publish to the directory](/docs/directory/publish)
  * If you haven't built the plugin yet, see [Build your first plugin](/docs/plugins/quickstart) and [Plugin structure and testing](/docs/plugins/build)
</Note>

## Choose a rollout route

The table compares organization settings on claude.ai with Claude Code managed settings on who receives the plugin and what each route asks of you.

|                           | Organization settings on claude.ai                                                                                 | Claude Code managed settings                                                                                                    |
| :------------------------ | :----------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |
| Who receives the plugin   | Members, on their claude.ai account: in chat, in Cowork, and in Claude Code sessions that sync from that account   | Claude Code on every machine that receives the settings                                                                         |
| Where you set it up       | [**Organization settings > Plugins & skills**](https://claude.ai/admin-settings/skills?tab=inventory)              | Server-managed settings, an MDM policy, or a `managed-settings.json` file                                                       |
| What you set              | An availability for each plugin, such as **Installed by default** or **Required**                                  | `extraKnownMarketplaces` to register your marketplace and `enabledPlugins` to install plugins from it                           |
| Access to your repository | Members need none. Organization sync reads the repository through your organization's GitHub or GitLab connection. | Each machine fetches the marketplace itself. For a private Git repository, it uses the Git credentials already on that machine. |
| Which components load     | Depends on the surface. See [Plugin feature support across platforms](/docs/plugins/platform-support).                  | Every component                                                                                                                 |
| Full setup steps          | [Manage plugins for your organization](/docs/plugins/admin)                                                             | [Manage Claude Code plugins for your organization](https://code.claude.com/docs/en/plugins/org) in the Claude Code docs         |

A plugin on a member's account reaches Claude Code as a synced plugin in Cowork and in terminal sessions where the member signs in with their claude.ai account on Claude Code v2.1.273 or later. [Plugins synced from claude.ai](https://code.claude.com/docs/en/plugins/loading#synced-plugins) has the sign-in and timing rules. For developers whose terminal sessions don't sync from a claude.ai account, use managed settings.

## Roll out through both routes

Use both routes when the plugin is for people in chat and Cowork and also for developers whose Claude Code sessions don't sync from a claude.ai account.

<Steps>
  <Step title="Lay out the repository as a marketplace">
    Put the plugin in a Git repository with a `.claude-plugin/marketplace.json` that lists it. You use the same repository for both routes. [Create a marketplace](https://code.claude.com/docs/en/plugins/create-marketplace) in the Claude Code docs covers the format.
  </Step>

  <Step title="Check the repository against the organization sync rules">
    Organization sync is stricter than Claude Code about the repository's visibility and about which plugin source types it accepts, and it rejects a plugin with a top-level `bin/` directory. Check [the plugin sources that organization sync accepts](/docs/plugins/org-sync#plugin-sources-that-organization-sync-accepts) before you continue.
  </Step>

  <Step title="Sync the repository from organization settings">
    In [**Organization settings > Plugins & skills**](https://claude.ai/admin-settings/skills?tab=inventory), add the repository as [Add your own plugins](/docs/plugins/admin#add-your-own-plugins) describes, then [set each plugin's availability](/docs/plugins/admin#set-availability).
  </Step>

  <Step title="Register the same marketplace in managed settings">
    Set `extraKnownMarketplaces` and `enabledPlugins` as [Pre-install and require plugins](https://code.claude.com/docs/en/plugins/org#pre-install-and-require-plugins) describes. To limit developers to your marketplace, see [Restrict what users can install](https://code.claude.com/docs/en/plugins/org#restrict-what-users-can-install).
  </Step>

  <Step title="Confirm on each surface">
    * **In claude.ai**: as a member, open [**Customize > Plugins**](https://claude.ai/customize/plugins) and check that the plugin appears there
    * **On a developer's machine**: start Claude Code and run `/plugin`, which lists the marketplace and the plugin
  </Step>
</Steps>

### If a developer has the plugin from both routes

A developer can end up with the plugin from both routes. Claude Code loads one plugin per name. It loads the copy that managed settings install and reports the synced copy as not loaded, as [Name conflicts](https://code.claude.com/docs/en/plugins/loading#name-conflicts) describes.

## Build one repository for both audiences

One plugin folder can serve both audiences, because each surface skips the components it doesn't load. Hooks and agents load in Cowork and Claude Code and not in chat, and a local MCP server doesn't run in chat. Check each component you include against [Plugin feature support across platforms](/docs/plugins/platform-support) before you promise a behavior to people who only use chat.

## Update a plugin you've rolled out

You release an update by pushing to the repository. How the update reaches people depends on the route.

### Update through organization settings

Organization sync reads the repository's default branch, and members get the new version after the marketplace syncs. It syncs when an Owner selects **Re-sync** or, with **Sync automatically** on, when someone pushes to the default branch. Nothing syncs on a schedule. Tags aren't read, so a tag by itself releases nothing.

**Re-sync** syncs the marketplace now, so members get the version on the default branch without waiting for a push. To re-sync:

<Steps>
  <Step title="Open the Marketplaces tab">
    Go to [**Organization settings > Plugins & skills > Marketplaces**](https://claude.ai/admin-settings/skills?tab=marketplaces).
  </Step>

  <Step title="Re-sync the marketplace">
    Open the menu in the marketplace's row and select **Re-sync**.
  </Step>

  <Step title="Retry if you synced recently">
    If you see **You synced recently**, wait the number of seconds the message gives, then select **Re-sync** again.
  </Step>
</Steps>

### Update through managed settings

Claude Code refreshes a marketplace and updates the plugins installed from it when auto-update is on for that marketplace. [Set update policy](https://code.claude.com/docs/en/plugins/org#set-update-policy) covers turning it on for your fleet.

If your `plugin.json` sets `version`, raise it with every release, because Claude Code compares it to decide whether an installed plugin has an update.

## Next steps

* [Sync your organization's plugins from a repository](/docs/plugins/org-sync): check your repository and plugin sources against the rules organization sync enforces
* [Manage plugins for your organization](/docs/plugins/admin): set availability for everyone or for user groups, and control what members can add themselves
* [Manage Claude Code plugins for your organization](https://code.claude.com/docs/en/plugins/org): set the managed-settings keys and deliver them to developers' machines

plugins/org-sync New page · 113 lines, new page

# Sync your organization's plugins from a repository ## Give organization sync access to your repository ### Sync a marketplace from github.com ### Sync a GitLab-hosted marketplace ## Plugin sources that organization sync accepts ### Keep executables out of the top-level bin directory ## Next steps

A whole new page. There's nothing to diff it against, so here is what it says.

# Sync your organization's plugins from a repository

> Distribute your organization's plugins from a GitHub or GitLab repository through organization settings, including repository requirements and GitLab setup.

You can distribute your organization's own plugins by syncing a Git repository that holds them from [**Organization settings > Plugins & skills**](https://claude.ai/admin-settings/skills?tab=inventory). Members then find those plugins under **Customize > Plugins** with the availability you set.

This page is for the Owner who adds the repository and for the engineer who maintains it. It covers the requirements the repository and its plugin entries must meet for the sync to accept them.

<Note>
  * If you're choosing who gets each plugin once the repository syncs, see [Manage plugins for your organization](/docs/plugins/admin#set-availability)
  * If you're writing the `marketplace.json` file, see [Create a marketplace](https://code.claude.com/docs/en/plugins/create-marketplace) in the Claude Code docs
</Note>

To get started, check [how organization sync gets access to your repository](#give-organization-sync-access-to-your-repository) for your Git host, then check your `marketplace.json` against [the plugin sources that organization sync accepts](#plugin-sources-that-organization-sync-accepts).

## Give organization sync access to your repository

Members don't need access to the repository themselves, and their Git credentials aren't involved. Organization sync reads the marketplace repository's default branch through your organization's GitHub or GitLab connection on claude.ai, whichever matches the repository's host:

* **github.com**: the Claude GitHub App, which you install during [Sync a marketplace from github.com](#sync-a-marketplace-from-github-com)
* **Your GitHub Enterprise Server host**: your organization's [GitHub Enterprise App](https://code.claude.com/docs/en/github-enterprise-server#admin-setup)
* **gitlab.com or your self-managed GitLab instance**: the access token in your organization's [GitLab configuration](#sync-a-gitlab-hosted-marketplace) for that host

### Sync a marketplace from github.com

When you sync a marketplace from github.com, organization sync reads the repository through the Claude GitHub App, and you choose the availability its plugins start with as you add it. To sync a marketplace from a private or internal repository on github.com:

<Steps>
  <Step title="Open Plugins & skills">
    Go to [**Organization settings > Plugins & skills**](https://claude.ai/admin-settings/skills?tab=inventory).
  </Step>

  <Step title="Select Sync from GitHub">
    Select **Add**, then **Sync from GitHub**.
  </Step>

  <Step title="Connect to GitHub">
    If the dialog shows **Connect to GitHub**, select it and authorize. GitHub returns you to the dialog.
  </Step>

  <Step title="Choose the repository">
    Search for the repository or enter it as `owner/repo`. The list shows private and internal repositories.
  </Step>

  <Step title="Install the Claude GitHub App if needed">
    If the repository isn't in the list, select **Install the Claude GitHub App** under **Repository missing?**, grant the app access to the repository on GitHub, and return to the dialog.
  </Step>

  <Step title="Leave automatic sync on">
    Leave **Sync automatically** on to sync each time someone pushes to the default branch. Claude creates the webhook on the repository for you.
  </Step>

  <Step title="Choose the default access">
    Choose the **Default access** for the plugins in this marketplace.
  </Step>

  <Step title="Create the marketplace">
    Select **Create**.
  </Step>
</Steps>

The marketplace's page opens, and **Last synced** shows **Syncing...** until the first sync finishes. If the dialog says **The Claude GitHub App is not installed on** the repository, grant the Claude GitHub App access to the repository on GitHub and try again.

To turn on automatic sync later, open the marketplace from the [**Marketplaces**](https://claude.ai/admin-settings/skills?tab=marketplaces) tab and turn on **Sync automatically**. If it shows **No webhook yet**, select **Configure webhook**, then **Enable webhook**.

### Sync a GitLab-hosted marketplace

Syncing a marketplace from GitLab needs a GitLab configuration for the host first, which holds the access token that organization sync reads the repository with. To sync a marketplace from gitlab.com or a self-managed GitLab instance:

<Steps>
  <Step title="Add a GitLab configuration">
    As an [Owner](https://code.claude.com/docs/en/server-managed-settings#access-control), add a GitLab configuration for that host at [**Organization settings > Claude Code**](https://claude.ai/admin-settings/claude-code). GitLab configurations are in public beta and apply only to plugin marketplace sync.
  </Step>

  <Step title="Sync from GitLab">
    In [**Organization settings > Plugins & skills**](https://claude.ai/admin-settings/skills?tab=inventory), select **Add**, then **Sync from GitLab**, as [Add your own plugins](/docs/plugins/admin#add-your-own-plugins) describes. When you add it, enter the project's HTTPS URL, such as `https://gitlab.example.com/platform/claude-plugins`.
  </Step>
</Steps>

Organization sync reads the project's default branch. If you turn on **Sync automatically**, only pushes to the default branch start a sync.

## Plugin sources that organization sync accepts

The repository you sync is a [plugin marketplace](https://code.claude.com/docs/en/plugins/create-marketplace): it has a `.claude-plugin/marketplace.json` file that lists your plugins and the location of each one. On a Team or Enterprise plan, organization sync applies these rules to the marketplace repository and to each plugin source the marketplace lists:

* **Marketplace repository**: on github.com and gitlab.com, the marketplace repository must be private or internal
* **Plugin source types**: each plugin source must be of type `github`, `url`, or `git-subdir`, or a [relative path](https://code.claude.com/docs/en/plugins/marketplace-reference#relative-path-plugin-source) that starts with `./`. If you list a plugin by bare name under `metadata.pluginRoot`, organization sync rejects it as an unsupported source. Write the path out instead, such as `./plugins/deploy-tools`
* **Private plugin sources**: a plugin source can be private when it's one of the following:
  * A github.com source that shares the marketplace repository's owner
  * A source on your organization's GitHub Enterprise host with the GitHub Enterprise App installed on the repository
  * A `url` or `git-subdir` source on the same GitLab host as the marketplace repository. On gitlab.com, the source must also be under the same top-level group or user namespace as the marketplace repository
* **Public plugin sources**: any other plugin source must be a public repository on github.com, gitlab.com, or bitbucket.org, which organization sync fetches without credentials. Organization sync rejects plugin sources on hosts these rules don't cover

To include private plugins, place the plugin folders inside the marketplace repository and reference them with a relative path. Organization sync packages each plugin during distribution, so members never need access to a separate source repository. For example, this `marketplace.json` plugin entry references a plugin you committed at `plugins/deploy-tools` in the marketplace repository:

```json theme={null}
{
  "name": "deploy-tools",
  "source": "./plugins/deploy-tools"
}
```

### Keep executables out of the top-level bin directory

Don't include a top-level `bin/` directory in any plugin you distribute through organization settings. claude.ai rejects a plugin that has one, whether the plugin arrives by marketplace sync or by direct upload in [**Organization settings > Plugins & skills**](https://claude.ai/admin-settings/skills?tab=inventory). The error message starts with `Plugin contains a top-level bin/ directory`. On marketplace sync, organization sync rejects that plugin and syncs the rest of the marketplace.

Keep executables in another directory, such as `scripts/`, and reference them as `${CLAUDE_PLUGIN_ROOT}/scripts/<name>` from your [skills, hooks, or MCP server configs](https://code.claude.com/docs/en/plugins/manifest-reference#environment-variables).

## Next steps

* [Manage plugins for your organization](/docs/plugins/admin#set-availability): set each synced plugin to available, installed by default, or required
* [Roll out a plugin to your whole organization](/docs/plugins/org-rollout): reach members in claude.ai and Cowork and developers in the Claude Code command line with one plugin
* [Create a marketplace](https://code.claude.com/docs/en/plugins/create-marketplace) in the Claude Code docs: write the `marketplace.json` file that lists your plugins

plugins/overview Changed · +124 / -67 lines

# Plugins ## Install a plugin ### Before you add a plugin ### Find and add a plugin ### Find the plugin in each app ### Bundled connectors ### Plugins your organization installs or requires ## Use a plugin ## Compare what each plugin component adds ## Manage installed plugins ## Track plugin usage in your organization ## Create your own plugin # Plugins overview ## What plugins do ## Plugin directory ## Origins in Claude Code ## Plugins in Cowork ## How plugins compose capabilities ## Availability

plugins/platform-support New page · 59 lines, new page

# Plugin feature support across platforms ## Compare component support by app ## Compare installation, sync, and admin controls ## Related resources

A whole new page. There's nothing to diff it against, so here is what it says.

# Plugin feature support across platforms

> Look up which plugin components and install paths work in claude.ai chat, Cowork, and Claude Code, and why a plugin behaves differently on each.

You can install the same plugin folder everywhere you use Claude, but chat, Cowork, and Claude Code each load a different subset of what the folder can contain. A surface skips a component it doesn't load, so a plugin can look complete in one place and partial in another.

This page is for anyone checking a component or behavior before relying on it, whether you're installing a plugin, building one, or submitting one to the directory.

<Note>
  * If you want to install and manage plugins, see [Plugins](/docs/plugins/overview)
  * If you're building a plugin, see [Plugin structure and testing](/docs/plugins/build)
  * If you run Claude Desktop on your own model provider, see its [Feature matrix](/docs/third-party/claude-desktop/feature-matrix) for feature availability
  * If you want to know where MCP Apps render, see [Add interactive UI with MCP Apps](/docs/connectors/building/mcp-apps/getting-started)
</Note>

## Compare component support by app

The tables on this page use these column names:

* **Chat**: conversations in claude.ai on the web, in the Claude desktop app, and in the mobile apps
* **Cowork**: Cowork tasks in the desktop app
* **Claude Code**: the terminal, the IDE extensions, and the desktop app's Code tab

A component marked "Ignored" is skipped on that surface, and a component marked "Can't be installed" makes that surface refuse the whole plugin.

| Component                                                             | Chat                                                                              | Cowork                                                                            | Claude Code                       | Notes                                                                                       |
| :-------------------------------------------------------------------- | :-------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------- | :-------------------------------- | :------------------------------------------------------------------------------------------ |
| Skills (`skills/<name>/SKILL.md`)                                     | Loads                                                                             | Loads                                                                             | Loads                             | [Create custom skills](/docs/skills/how-to)                                                      |
| Commands (`commands/*.md`)                                            | Loads as a skill; Claude applies it when it fits                                  | Loads; you run it by typing `/plugin-name:command`                                | Loads                             |                                                                                             |
| Agents (`agents/*.md`)                                                | Ignored                                                                           | Loads                                                                             | Loads                             |                                                                                             |
| Hooks (`hooks/hooks.json`)                                            | Ignored                                                                           | Loads                                                                             | Loads                             | [Hooks](https://code.claude.com/docs/en/plugins/components#hooks) in the Claude Code docs   |
| Remote MCP server, `http` or `sse` with a fixed URL                   | Listed on the plugin's **Connectors** tab; works once you add or connect it there | Loads; connect it from the plugin's **Connectors** tab                            | Loads                             | [Bundle a connector with its skill](/docs/plugins/build#bundle-an-mcp-connector-with-its-skill)  |
| Local MCP server, a command the app starts, including `.mcpb` bundles | Ignored                                                                           | Loads when the Cowork session runs on your computer                               | Loads                             | On the web, the plugin's **Connectors** tab marks it **Runs in each session**               |
| MCP server that references `${user_config.*}` values                  | Ignored when the URL contains the reference                                       | Ignored when a referenced option has no default; Cowork doesn't prompt for values | Loads; prompts you for the values | [User configuration](https://code.claude.com/docs/en/plugins/components#user-configuration) |
| Executables in a top-level `bin/` directory                           | Can't be installed                                                                | Can't be installed                                                                | Loads                             |                                                                                             |
| LSP servers, output styles, themes, `settings`                        | Ignored                                                                           | Ignored                                                                           | Loads                             | [Plugin components](https://code.claude.com/docs/en/plugins/components)                     |

When you submit a plugin to the directory, the portal derives the surfaces it supports from these same rules and shows them to you before you submit.

## Compare installation, sync, and admin controls

Chat and Cowork read plugins from your claude.ai account, and Claude Code reads them from the machine it runs on.

|                                          | Chat and Cowork                                                                                                                                                                                                                  | Claude Code                                                                                             | Notes                                                                                                                                                |
| :--------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
| Where you add plugins                    | [**Customize > Plugins**](https://claude.ai/customize/plugins) in claude.ai or the desktop app                                                                                                                                   | `/plugin` in a session, or `claude plugin install`                                                      | [Plugins](/docs/plugins/overview), [Install plugins](https://code.claude.com/docs/en/plugins/install)                                                     |
| What an install is attached to           | Your account, for the organization you're in                                                                                                                                                                                     | The machine, at user, project, or local scope                                                           |                                                                                                                                                      |
| Which way installs travel                | A plugin you install on your account also appears in Claude Code as a synced plugin at the next session start                                                                                                                    | A plugin you install from the command line stays on that machine and isn't added to your account        | [Synced plugins](https://code.claude.com/docs/en/plugins/loading#synced-plugins)                                                                     |
| Hosts for a marketplace you add yourself | GitHub and GitHub Enterprise repositories, and public GitLab and Bitbucket repositories                                                                                                                                          | Any Git repository, GitHub shorthand, URL, or local path                                                | Repositories your organization syncs to distribute plugins follow [different rules](/docs/plugins/org-sync#plugin-sources-that-organization-sync-accepts) |
| Marketplace and plugin limits            | Up to 25 marketplaces that you add yourself, counted for your account in each organization. Each plugin can contain up to 5,000 files and 200 MB, and 200 MB is also the largest file that **Upload plugin** accepts.            | No account limits apply; installs are per machine                                                       |                                                                                                                                                      |
| Install from a file                      | **Add > Upload plugin** with a zip of the folder                                                                                                                                                                                 | `claude --plugin-dir <path>` for one session                                                            | [Plugin structure and testing](/docs/plugins/build#test-the-plugin-on-each-surface)                                                                       |
| Browse the directory                     | **Discover** in **Customize > Plugins**, on Pro, Max, Team, and Enterprise plans. On Team and Enterprise plans, an Owner can [remove the directory as a source](/docs/plugins/admin#manage-synced-marketplaces) for the organization. | Not in `/plugin`; a plugin added from the directory on claude.ai reaches Claude Code as a synced plugin | [Publish to the directory](/docs/directory/publish)                                                                                                       |
| Organization controls                    | An Owner sets each plugin to **Not available**, **Available to install**, **Installed by default**, or **Required**                                                                                                              | In managed settings, an admin allowlists or blocks marketplaces and force-installs plugins              | [Manage plugins for your organization](/docs/plugins/admin), and the [Claude Code equivalent](https://code.claude.com/docs/en/plugins/org)                |

## Related resources

* [Plugin structure and testing](/docs/plugins/build): lay out the plugin folder and write the manifest that all three surfaces load
* [Plugin components](https://code.claude.com/docs/en/plugins/components) in the Claude Code docs: look up every component type, including the Claude Code-only ones
* [Manage plugins for your organization](/docs/plugins/admin): as an Owner, set each plugin's availability for members

plugins/pre-submission-checklist New page · 197 lines, new page

# Plugin pre-submission checklist ## Run the checks before you submit ### Check the plugin on your machine (optional) ### Validate in the developer portal ### Read a validation result ## Review what validation and the scan check ### Repository and folder layout ### Manifest and plugin name ### README and license ### Files in the plugin folder ### Review what the plugin runs and connects to ### Choices a reviewer always checks ### Hooks, skills, commands, and agents ## Prepare for the security scan ## Test the plugin's behavior before you submit ## Next steps

A whole new page. There's nothing to diff it against, so here is what it says.

# Plugin pre-submission checklist

> Fix every finding before you submit a plugin to the Claude plugin directory: what the developer portal's validation and scan check, and what each result means.

Before the [Claude plugin directory](/docs/directory/publish) lists your plugin, the developer portal checks the plugin's files at two points. Validation runs in the plugin submission form at [claude.ai/directory/manage](https://claude.ai/directory/manage) when you select the **Validate** button. A scan runs after you submit, on each new commit that the directory picks up from the branch or tag that it follows. The scan checks the plugin's files again and runs a security scan.

Use this checklist to fix problems before you [submit your plugin](/docs/plugins/submit) from the developer portal on claude.ai. The checklist covers the automated checks only, and every plugin in the directory also has to follow the [Anthropic Software Directory Policy](https://support.claude.com/en/articles/13145358-anthropic-software-directory-policy). Start by [running the checks](#run-the-checks-before-you-submit) and [reading a validation result](#read-a-validation-result). Then use the tables in [what validation and the scan check](#review-what-validation-and-the-scan-check) to fix each finding, and [prepare for the security scan](#prepare-for-the-security-scan) that runs after you submit.

## Run the checks before you submit

Checking a plugin before you submit it takes three steps:

1. Optional: [check the plugin on your machine](#check-the-plugin-on-your-machine-optional) with Claude Code's `claude plugin validate` command, which catches syntax and schema errors before you push
2. [Validate in the developer portal](#validate-in-the-developer-portal), which runs every directory check in the tables on this page
3. [Read the result](#read-a-validation-result), fix every finding that the report marks **Blocking**, and then submit

The portal is open to the people who [can submit](/docs/directory/publish#confirm-you-can-submit-to-the-directory). If you can't submit, ask someone who can to run **Validate**.

### Check the plugin on your machine (optional)

If you have [Claude Code](https://code.claude.com/docs/en/setup), Anthropic's command-line coding tool, installed, you can catch syntax and schema errors before you push. Open a terminal in the folder that contains your plugin folder and run:

```bash theme={null}
claude plugin validate ./your-plugin
```

A plugin with no problems prints `✔ Validation passed`. Otherwise the output lists each error or warning with the file and field it's in; fix those and run the command again.

The `claude plugin validate` command only checks that your files are well-formed. It doesn't check the directory's requirements, such as whether you have a README and license or whether the name is taken; the portal's **Validate** checks those. [`plugin validate`](https://code.claude.com/docs/en/plugins/cli-reference#plugin-validate) in the Claude Code docs lists exactly what the command checks.

### Validate in the developer portal

The portal's **Validate** button runs every check in this page's tables against your repository and gives you a report before you submit anything.

<Steps>
  <Step title="Start a submission">
    Open the [developer portal](https://claude.ai/directory/manage) and select **Submit new**.
  </Step>

  <Step title="Choose Plugin bundle">
    When the portal asks **What would you like to submit?**, select **Plugin bundle**.
  </Step>

  <Step title="Enter the repository">
    On the **Source** step, enter the repository. [Submit your plugin](/docs/plugins/submit#submit-a-plugin) describes each field.
  </Step>

  <Step title="Validate">
    Select **Validate**. The report lists each finding with its result and, for many findings, a fix.
  </Step>

  <Step title="Fix blocking findings and validate again">
    The report covers only the commit that validation read, so it doesn't change when you push a fix. Push the fix, then select **Re-validate** on the **Source** step of the same form. When the new report has no findings with the **Blocks** result, continue through the form to submit the plugin.
  </Step>
</Steps>

### Read a validation result

Validation produces a report in the submission form, and the scan's results appear on the plugin's page in the developer portal. Each finding has one of these results:

* **Blocks:** the report marks the finding **Blocking**. You can't submit the plugin until you fix the problem and validate again
* **Held for a reviewer:** the report marks the finding **Policy hold**. You can submit, and an Anthropic reviewer reads the held version before it can go live. A hold isn't a rejection. The scan can raise the same hold again on each new version.
* **Warning:** the report shows the finding, and you can submit without fixing it. The plugin still has to follow the Anthropic Software Directory Policy
* **Note:** the report gives information, and nothing needs fixing

Some problems with the repository stop validation before there is a report. The submission form then shows one error, such as **Couldn’t validate that repository**, and no findings. The tables in [what validation and the scan check](#review-what-validation-and-the-scan-check) mark those checks as "Validation stops".

[Submit your plugin](/docs/plugins/submit#after-you-submit-a-plugin) explains how review and publishing proceed after you submit.

## Review what validation and the scan check

The plugin folder is the folder that contains `.claude-plugin/plugin.json`, the plugin's manifest. It can be the repository root or a subfolder. People who install the plugin get only the plugin folder, so everything the plugin runs has to be inside it.

Most checks read the plugin folder, and a few also read the rest of the repository. Fix every row marked **Blocks** before you submit.

Each table gives the result at validation, unless a row says that the result comes after you submit. For a finding with no title in the report, the report states the rule in words instead.

### Repository and folder layout

The repository and folder layout checks cover the plugin's location in the repository and what the repository as a whole contains.

| What to do                                                                                                                                                                                                                                                 | [Result if you don't](#read-a-validation-result)                      | Title in the report, if it has one                                                                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Submit a folder that contains `.claude-plugin/plugin.json`                                                                                                                                                                                                 | Blocks                                                                |                                                                                                                                                        |
| Submit one plugin at a time. In a [marketplace repository](https://code.claude.com/docs/en/plugins/create-marketplace) with several plugins, validate and submit each plugin folder on its own.                                                            | Blocks                                                                | **Pick one plugin first**, when you select **Submit for review**                                                                                       |
| Keep every file that a hook, an MCP server command, or a script uses inside the plugin folder, and point every component path in `plugin.json` inside it                                                                                                   | Blocks for a `plugin.json` path that points outside the plugin folder |                                                                                                                                                        |
| Commit regular files and folders for everything the plugin loads, not symbolic links, Git submodules, or Git LFS pointer files                                                                                                                             | Blocks where the plugin loads the entry. Warning elsewhere.           |                                                                                                                                                        |
| Remove `.DS_Store`, `Thumbs.db`, `desktop.ini`, and `__MACOSX` entries from the plugin folder                                                                                                                                                              | Blocks                                                                | In validation, a message that begins "This is a macOS or Windows system file". After you submit, **Files in the repository the scanner won’t accept**. |
| Use file and folder names that are valid on both Windows and macOS: no colon, no trailing dot or space, no Windows device name such as `con.md` or `prn`, and no two names that differ only by capitalization                                              | Validation stops                                                      | **Couldn’t validate that repository**                                                                                                                  |
| Name each folder on the path to the plugin with letters, digits, dots, hyphens, and underscores only, and enter the plugin path with the same capitalization as the repository                                                                             | Validation stops                                                      | **Couldn’t validate that repository**                                                                                                                  |
| Keep `export-ignore` and `export-subst` out of every `.gitattributes` file. Keep `filter`, Git LFS included, and other attributes that rewrite file contents out of `.gitattributes` files at the repository root, above the plugin folder, and inside it. | Validation stops                                                      | **Couldn’t validate that repository**                                                                                                                  |
| Keep the repository under 50 MiB as GitHub archives it and under 256 MiB unpacked, with fewer than 10,000 files and folders, and keep every file in the plugin folder under 5 MiB                                                                          | Validation stops                                                      | **Repository too large to validate**                                                                                                                   |

The file-name, plugin-path, and `.gitattributes` checks all produce **Couldn’t validate that repository**. The error doesn't say which cause applies, so check each of them. [Files in the plugin folder](#files-in-the-plugin-folder) has tighter file limits that hold a version for a reviewer.

### Manifest and plugin name

`plugin.json` is the plugin's manifest. Beyond the syntax and schema errors that `claude plugin validate` catches, the directory runs the checks in this table. Settle the name before you submit, and raise `version` with every release, as [version management](https://code.claude.com/docs/en/plugins/loading#versions-and-updates) describes.

| What to do                                                                                                                                                                                                                                                                                                                                                       | [Result if you don't](#read-a-validation-result)                                                                | Title in the report, if it has one                                                                                                                      |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Use a `name` made of lowercase letters, digits, and hyphens, up to 64 characters, that starts and ends with a letter or digit                                                                                                                                                                                                                                    | Blocks for non-ASCII characters. Warning for any other name that breaks the pattern, such as uppercase letters. | **Non-ASCII identifier** when blocked                                                                                                                   |
| Build the name around your own distinctive product or project name: not a reserved word such as `claude`, `anthropic`, `official`, `plugin`, `mcp`, or `test` as the whole name, not a [marketplace name reserved for Anthropic](https://code.claude.com/docs/en/plugins/marketplace-reference#reserved-names), and nothing that presents the plugin as official | Blocks. Held for a reviewer for a name made only of generic words, such as `test-plugin`.                       | **Name is taken** when blocked. **Name may be confused with an existing listing** when held.                                                            |
| Choose a name that no other organization's plugin uses. A name that differs only in capitalization or punctuation counts as the same name.                                                                                                                                                                                                                       | Blocks for the same name. Held for a reviewer for a look-alike.                                                 | **Name is taken** when blocked. **Name may be confused with an existing listing** when held.                                                            |
| Choose a name, `displayName`, and `author.name` that can't be mistaken for an existing plugin, publisher, connector, or well-known brand that isn't yours                                                                                                                                                                                                        | Held for a reviewer                                                                                             | **Name matches a known brand**, **Name may be confused with an existing listing**, or **Publisher name may be confused with another** for `author.name` |
| In a fork, give the plugin a name of its own. Forks are allowed.                                                                                                                                                                                                                                                                                                 | Held for a reviewer                                                                                             | **Fork uses the upstream project’s name**                                                                                                               |
| Write `displayName` and `author.name` in one writing system, without look-alike letters or invisible characters                                                                                                                                                                                                                                                  | Blocks                                                                                                          |                                                                                                                                                         |
| Spell the keys that declare components, such as `hooks` and `mcpServers`, exactly as the [plugins reference](https://code.claude.com/docs/en/plugins/manifest-reference) does, and keep them out of the `experimental` object                                                                                                                                    | Blocks                                                                                                          |                                                                                                                                                         |
| Set `description`, `author`, and `version`                                                                                                                                                                                                                                                                                                                       | Warning                                                                                                         |                                                                                                                                                         |

### README and license

The directory shows your README as the listing's description and requires a license before it lists the plugin.

| What to do                                                                                                                  | [Result if you don't](#read-a-validation-result) | Title in the report, if it has one       |
| --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------- |
| Put a README of at least 40 words in the plugin folder, preferably named `README.md`. Words inside code blocks don't count. | Blocks                                           | **README missing**, **README too short** |
| Add a `LICENSE` file to the plugin folder, or set `license` in `plugin.json`                                                | Blocks                                           | **License missing**                      |

### Files in the plugin folder

The file checks apply to every file in the plugin folder, including images and documents.

| What to do                                                                                                                                                                                           | [Result if you don't](#read-a-validation-result)             | Title in the report, if it has one                    |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------- |
| Keep every file that isn't an image or font under 256 KiB                                                                                                                                            | Held for a reviewer                                          | **Files or downloads the validator couldn’t inspect** |
| Keep the plugin to 512 files or fewer                                                                                                                                                                | Held for a reviewer                                          | **Files or downloads the validator couldn’t inspect** |
| Include only text files, SVG included, complete PNG, JPEG, GIF, and WebP images, and font files. Any other binary file, such as an `.ico`, `.pdf`, or `.zip` file or a compiled executable, is held. | Held for a reviewer                                          | **Files or downloads the validator couldn’t inspect** |
| To show a bundled image in the README, use Markdown image syntax. Don't refer to bundled images or fonts from commands, hooks, or scripts, or write their paths in backticks or a code block.        | Held for a reviewer                                          |                                                       |
| Declare each MCP server with `command` and `args` or with `url`, not a `.mcpb` or `.dxt` bundle                                                                                                      | Held for a reviewer. Blocks for a bundle fetched from a URL. | **Bundled MCP server not inspected** when held        |

### Review what the plugin runs and connects to

A package launcher is a command that downloads a package and runs it: `npx`, `bunx`, `pnpm dlx`, `yarn dlx`, `uvx`, `pipx run`, and `uv run` all count. `${CLAUDE_PLUGIN_ROOT}` is the variable that Claude Code sets to the plugin's installation directory.

| What to do                                                                                                                                                                                                                                                                                           | [Result if you don't](#read-a-validation-result)                        | Title in the report, if it has one                                    |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------- |
| Pin every package that a launcher runs to an exact version, such as `npx <package>@1.2.3` or `uvx <package>==1.2.3`, not a range or `@latest`. Run `uv run` with `--locked` or `--frozen`.                                                                                                           | Blocks                                                                  | **Unpinned npx launcher**, **Unpinned uvx launcher**                  |
| In a plugin that uses a launcher or runs a package install, don't include a package-manager configuration file that sets a registry, index, proxy, or other package source, such as `.npmrc`, `bunfig.toml`, or `uv.toml`                                                                            | Blocks with a launcher. Held for a reviewer with a package install.     | **Install may use a custom registry or package source** when held     |
| Keep real credentials out of every file, documentation and examples included. Ask for each value through a `userConfig` entry in `plugin.json` with `sensitive: true`, and refer to it as `${user_config.KEY}`.                                                                                      | Blocks                                                                  | **Secret in MCP headers** for a credential in an MCP server's headers |
| Don't read a credential that is already set in the user's environment, such as `$GITHUB_TOKEN`, and send it to a server, even in a README example. Ask for it through `userConfig` instead.                                                                                                          | Held for a reviewer. Blocks for an HTTP hook that sends the credential. | **Uses a credential from the user’s machine** when held               |
| Make `.mcp.json` valid JSON in which every server entry matches the schema in the [MCP documentation](https://code.claude.com/docs/en/mcp)                                                                                                                                                           | Blocks                                                                  | **.mcp.json can’t be parsed** for invalid JSON                        |
| Give each remote MCP server a `type` of `http`, `sse`, or `ws` and a `url` that is an absolute `https://` or `wss://` URL, a `${user_config.KEY}` reference, or `""` when the plugin has no fixed endpoint                                                                                           | Blocks                                                                  | **MCP server URL is not https** for a URL with another scheme         |
| Start each local MCP server by running a file in the plugin with plain arguments, such as `node ${CLAUDE_PLUGIN_ROOT}/server.js`, not through a shell, an inline program such as `-c`, or a package-manager script such as `npm run`                                                                 | Held for a reviewer                                                     | **MCP server command wasn’t read**                                    |
| In the command of a hook or an MCP server, write each path in full from `${CLAUDE_PLUGIN_ROOT}`, with no other variable, command substitution, wildcard, or inline program such as `python3 -c`                                                                                                      | Blocks when the plugin folder is a subfolder of the repository          |                                                                       |
| Keep launchers and package installs out of each script that a hook or an MCP server runs. When the plugin folder is a subfolder of the repository, also keep shell variables other than `${CLAUDE_PLUGIN_ROOT}`, command substitutions, and calls to other files in the plugin out of those scripts. | Held for a reviewer                                                     | **Scripts the validator couldn’t follow**                             |

### Choices a reviewer always checks

These choices are held for a reviewer even when the plugin meets every other check:

* **A package from a registry:** a launcher that runs a package pinned to an exact version, or `uv run` with `--locked` or `--frozen`, is still held, because the package's own dependencies resolve at install time. The finding is **Runs a pinned npx or uvx package**
* **A lockfile install:** `package.json` beside `package-lock.json`, `npm-shrinkwrap.json`, `bun.lock`, or `bun.lockb` in the root of the plugin folder is held, because Claude Code [installs the packages in that lockfile](https://code.claude.com/docs/en/plugins/loading#node-js-package-dependencies) when a user installs the plugin. The finding is **Dependencies install from a lockfile**
* **A program the validator can't read through, when the plugin folder is a subfolder of the repository:** the validator follows only plain shell scripts. When a hook, an MCP or LSP server command, or a `` !`…` `` line in a skill or command runs a non-shell file from the plugin, passes a whole directory to an interpreter, or runs a shell script that itself runs another file, that file is held. A script that `SKILL.md` only tells Claude to run isn't part of this check. To avoid the hold, keep the plugin at the root of its own repository, or keep the logic a hook or server runs in shell scripts that name each path as `${CLAUDE_PLUGIN_ROOT}/<file>`. The finding is **Scripts the validator couldn’t follow**

If you bundle a package's code into the plugin instead, the launcher or install finding no longer applies, and a reviewer hold can still apply. Validation and the scan check the bundled file like every other file in the plugin folder, including the 256 KiB limit in [Files in the plugin folder](#files-in-the-plugin-folder).

### Hooks, skills, commands, and agents

The component checks confirm that Claude Code can load each hook, skill, command, and agent file in the plugin.

| What to do                                                                                                                                                                                                       | [Result if you don't](#read-a-validation-result)                                                                                | Title in the report, if it has one         |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| Make `hooks/hooks.json` valid JSON with a top-level `hooks` object, only the hook events and hook types in the [hooks reference](https://code.claude.com/docs/en/hooks), and an `https://` URL on each HTTP hook | Blocks                                                                                                                          | **hooks.json is invalid** for invalid JSON |
| Leave `hooks/hooks.json` out of the `hooks` field in `plugin.json`, because Claude Code loads that file automatically                                                                                            | Warning                                                                                                                         |                                            |
| Write valid YAML front matter in each skill, command, and agent file, with `description` as a single text value, not a list                                                                                      | Blocks for front matter that doesn't parse or a `description` that isn't text. Warning for no front matter or no `description`. |                                            |
| Name component folders and files with the exact spelling and capitalization Claude Code expects, such as `hooks/`, `skills/`, and `SKILL.md`                                                                     | Blocks                                                                                                                          |                                            |

## Prepare for the security scan

The security scan looks for behavior that a plugin doesn't disclose, such as sending data elsewhere, running hidden code, or changing Claude's permission settings.

A first submission that fails the security scan is rejected, and a later version that fails can't go live. A new version that the scan flags is held for a reviewer. The **Versions** tab on the plugin's page in the developer portal shows **Didn’t pass the security scan**, or the category of the finding, such as **Sends data to an undisclosed destination**. [Submit your plugin](/docs/plugins/submit#fix-a-failed-version) explains what to do when a version doesn't pass.

To prepare, make the plugin's behavior visible in its README and its source:

* Describe in the README everything the plugin runs, sends, or fetches. A complete README doesn't make a behavior allowed. The [Anthropic Software Directory Policy](https://support.claude.com/en/articles/13145358-anthropic-software-directory-policy) sets what a plugin is allowed to do
* Commit readable source instead of compiled, packed, or minified code. Code that the security scan can't read is held for a reviewer

## Test the plugin's behavior before you submit

Validation and the scan check how the plugin is built. They don't check whether the plugin helps the people who install it. Before you submit, test the plugin's output and how it loads on the surfaces your users will use:

<Steps>
  <Step title="Compare output with and without the plugin">
    Run the plugin's skills on real prompts and compare the output with what Claude produces without the plugin. [`claude plugin eval`](https://code.claude.com/docs/en/plugin-evals) runs that comparison for the whole plugin in Claude Code, and [Measure whether the skill improves the output](/docs/skills/how-to#measure-whether-the-skill-improves-the-output) covers one skill at a time.
  </Step>

  <Step title="Load the plugin on each surface">
    Load the plugin on each surface your users will use, as [Test the plugin on each surface](/docs/plugins/build#test-the-plugin-on-each-surface) describes.
  </Step>
</Steps>

## Next steps

* [Submit your plugin](/docs/plugins/submit): enter the repository in the developer portal, follow the review, and publish
* [Publish to the directory](/docs/directory/publish): confirm your plan and role can submit, and see what Anthropic's review involves

plugins/quickstart New page · 187 lines, new page

# Build your first plugin ## Before you create the plugin ## Create the plugin ## Test the plugin in Claude Code ## Validate the plugin ## Push the plugin to GitHub ## Submit your own plugin ## Next steps

A whole new page. There's nothing to diff it against, so here is what it says.

# Build your first plugin

> Build a plugin with one skill and an optional MCP connector, test it in Claude Code, validate it, and push it to GitHub, ready to submit your own.

By the end of this quickstart, you have a working example plugin with one skill and, optionally, one remote MCP connector, tested in Claude Code, validated, and pushed to GitHub, which is everything a plugin needs before you submit it to [Anthropic's directory](/docs/directory/publish). A plugin is a folder that packages skills, MCP connectors, commands, and agents, in any combination, so that people add them together.

This quickstart is for developers who have Claude Code installed and want to learn the plugin format by building one. You can follow it with a product that has a remote MCP server, or with only a skill.

<Note>
  * If you want to make a plugin from a conversation without writing files, see [Create a plugin with Claude](/docs/plugins/create-with-claude)
  * If you want to distribute a plugin only inside your own organization, see [Roll out a plugin to your whole organization](/docs/plugins/org-rollout)
  * If you want to look up the folder layout, the manifest fields, or what each surface loads, see [Plugin structure and testing](/docs/plugins/build)
</Note>

## Before you create the plugin

Check that you have each of these before you create the plugin:

* **Claude Code**: [install Claude Code](https://code.claude.com/docs/en/setup). You use it to test and validate the plugin
* **A GitHub repository**: the directory reads plugins from repositories on github.com, and the repository must be public before the listing goes live

## Create the plugin

The steps in this section build a plugin named `expense-reports` for a fictional finance product whose MCP server is at `mcp.example.com`. Replace the names and values with your own.

<Steps>
  <Step title="Write the manifest">
    Create a folder named `expense-reports`, and create `.claude-plugin/plugin.json` inside it. Put only the manifest inside `.claude-plugin/`. Everything else goes at the plugin's top level.

    The directory requires the manifest, and the example has the fields that every surface and the directory read:

    ```json theme={null}
    {
      "name": "expense-reports",
      "displayName": "Expense Reports",
      "version": "1.0.0",
      "description": "File, track, and approve expense reports from a conversation, using your finance system's connector and your company's approval rules.",
      "author": { "name": "Example Corp", "url": "https://example.com" },
      "license": "MIT"
    }
    ```

    People install and refer to the plugin by its `name`. Use lowercase words joined by hyphens, make the name specific to your product, and never change it after release. [Manifest and plugin name](/docs/plugins/pre-submission-checklist#manifest-and-plugin-name) lists the directory's checks on the name.
  </Step>

  <Step title="Add a skill">
    Create `skills/file-expense/SKILL.md`. A skill tells Claude when and how to do a task. The example calls tools from the MCP connector that you add in the next step, so leave the tool calls out of your own skill if your plugin has no connector:

    ```markdown theme={null}
    ---
    name: file-expense
    description: File an expense report. Use when the user mentions a receipt, reimbursement, or expense, or asks to submit spending for approval.
    ---

    To file an expense:

    1. Ask for the receipt if the user hasn't attached one, and read the amount, date, merchant, and currency from it.
    2. Call the expenses connector's `create_report` tool with those fields. Default the category from the merchant type; ask only if it's ambiguous.
    3. If the amount is over the user's approval limit (check with `get_policy`), add their manager as approver before submitting.
    4. Reply with the report number and its approval status. Don't paste the full API response.
    ```

    Claude decides when to load the skill from the `description` line, so write it as the situations a user would be in. [Create custom skills](/docs/skills/how-to) covers the frontmatter fields, resource files, scripts, and testing.
  </Step>

  <Step title="Add an MCP connector">
    Skip this step if your plugin has only a skill. If your product has a remote MCP server, create `.mcp.json` at the plugin root and reference the server by URL:

    ```json theme={null}
    {
      "mcpServers": {
        "expenses": {
          "type": "http",
          "url": "https://mcp.example.com/mcp"
        }
      }
    }
    ```

    There is no server at `mcp.example.com`, so this example connector fails to connect when you test the plugin. Replace the URL with your own server's, or leave `.mcp.json` out.

    Don't put API keys or other secrets in this file, because every person who installs the plugin receives its files. On claude.ai and in Cowork, the entry is listed on the plugin's **Connectors** tab, where the user [adds or connects it](/docs/plugins/overview#bundled-connectors) and signs in through your server's OAuth flow. On Team and Enterprise plans, an Owner adds the connector for the organization, and members then connect with their own account.
  </Step>

  <Step title="Write the README">
    Create `README.md` in the plugin folder with at least 40 words. Words inside code blocks don't count. Say what the plugin does, how to use it, and what data it sends. The directory shows your README as the listing's description, and [README and license](/docs/plugins/pre-submission-checklist#readme-and-license) lists what validation checks.

    This README covers those three points for the example plugin:

    ```markdown theme={null}
    # Expense Reports

    File, track, and approve expense reports from a conversation with Claude.

    ## Use it

    Attach a receipt and ask Claude to file it. Claude reads the amount, date,
    and merchant, files the report through the Expense Reports connector, and
    replies with the report number. Ask what's waiting on you to list the
    reports that need your approval.

    ## Data

    The plugin sends receipt details and report fields to your Example Corp
    account through mcp.example.com. It stores nothing itself.
    ```
  </Step>

  <Step title="Check the license">
    The directory requires a `LICENSE` file in the plugin folder or `license` in `plugin.json`, and validation blocks a plugin that has neither. The example manifest sets `license`, which meets the requirement. If you remove that field, add a `LICENSE` file to the plugin folder instead.
  </Step>
</Steps>

## Test the plugin in Claude Code

Load the plugin from your working copy before you push it. From the folder that contains `expense-reports`, start a Claude Code session with the plugin loaded:

```bash theme={null}
claude --plugin-dir ./expense-reports
```

In that session, your skill appears as `/expense-reports:file-expense`. If you added the connector, `/mcp` shows the server's connection state. With the example's `mcp.example.com` URL, the `expenses` server shows as failed because no server exists at that address, and Claude reports that it can't reach the server when the skill calls its tools.

To try the skill, describe one of the situations that its `description` line names, such as a receipt you want reimbursed. Claude decides when to load the skill from that line.

To test the plugin on claude.ai and in Cowork as well, see [Test the plugin on each surface](/docs/plugins/build#test-the-plugin-on-each-surface).

## Validate the plugin

Run `claude plugin validate` on the folder to catch syntax and schema errors on your machine before you push:

```bash theme={null}
claude plugin validate ./expense-reports
```

The command prints `✔ Validation passed` when the manifest and the component files parse, and names the field to fix when they don't.

The plugin is checked at these points before it's listed, and the portal checks more than the command does:

* **The command**: checks the plugin for syntax and schema errors
* **Validate in the developer portal**: the **Validate** button in the [developer portal](https://claude.ai/directory/manage) runs every validation check. The directory's own checks, such as the README, license, and name checks, run there and not in the command
* **The scan after you submit**: checks the plugin's files again and runs a security scan

The [Plugin pre-submission checklist](/docs/plugins/pre-submission-checklist) lists every check and what each result means.

## Push the plugin to GitHub

The directory reads plugins from repositories on github.com, so the plugin folder goes in a GitHub repository.

<Steps>
  <Step title="Create the repository">
    Create an empty repository on github.com for the plugin. The repository must be public before the listing goes live.
  </Step>

  <Step title="Remove system files">
    Remove `.DS_Store`, `Thumbs.db`, `desktop.ini`, and `__MACOSX` entries from the plugin folder, and add them to `.gitignore`. Validation blocks a plugin that contains them.
  </Step>

  <Step title="Commit and push">
    From inside the `expense-reports` folder, commit the files and push them. The example pushes to a repository named `example-corp/expense-reports`, so replace that name with your own:

    ```bash theme={null}
    git init -b main
    git add .
    git commit -m "Add the expense-reports plugin"
    git remote add origin https://github.com/example-corp/expense-reports.git
    git push -u origin main
    ```

    The repository's page on github.com now shows `.claude-plugin/`, `skills/`, and the other plugin files at the repository root.
  </Step>
</Steps>

## Submit your own plugin

The `expense-reports` plugin you built on this page is a small demonstration of the format, so there's no reason to submit it: the directory is for plugins other people will use, and it refuses a name another organization has already listed. Use the same steps to build your own plugin, with its own name, skills, and connector.

When your plugin validates and is pushed to a public GitHub repository, submit it from the developer portal at [claude.ai/directory/manage](https://claude.ai/directory/manage): select **Submit new**, choose **Plugin bundle**, and follow [Submit a plugin](/docs/plugins/submit#submit-a-plugin) for each field and for what happens after you submit. If your plugin points at a remote MCP server you run, [submit that server as a connector too](/docs/directory/publish#submit-your-plugin-and-your-mcp-server-as-a-connector). [Who can submit to the directory](/docs/directory/publish#confirm-you-can-submit-to-the-directory) has the plan and role requirements.

## Next steps

* [Plugin structure and testing](/docs/plugins/build): look up the folder layout and manifest fields, and test on claude.ai and in Cowork
* [Plugin pre-submission checklist](/docs/plugins/pre-submission-checklist): fix each validation and scan finding before you submit
* [Submit a plugin](/docs/plugins/submit): fill in each portal field, then publish and update the listed plugin
* [Track your submission](/docs/directory/submission-status): check what your submission's status means and who acts next
* [Plugin feature support across platforms](/docs/plugins/platform-support): check which of the plugin's components load in chat, Cowork, and Claude Code
* [`claude plugin eval`](https://code.claude.com/docs/en/plugin-evals): write eval cases and compare the plugin's results against a run without the plugin

plugins/share New page · 92 lines, new page

# Share a plugin with teammates ## Share a plugin with specific people ### Choose how to distribute a plugin ### Share the plugin ### What the people you share with get ### Stop sharing a plugin ### If you can't share a plugin ## Publish a plugin to your organization ## Next steps

A whole new page. There's nothing to diff it against, so here is what it says.

# Share a plugin with teammates

> Share a plugin you made with specific people in your Team or Enterprise organization, or publish it to your organization's library.

On a Team or Enterprise plan, you can get a [plugin](/docs/plugins/overview) you made to other people in your organization. You share it with specific people yourself, or you publish it to your organization's library, where an Owner decides who can find and install it.

This page is for someone on a Team or Enterprise plan who created or uploaded a plugin, for example with [Create a plugin with Claude](/docs/plugins/create-with-claude).

<Note>
  * If you're an Owner reviewing what members publish, see [Manage plugins for your organization](/docs/plugins/admin)
  * If you want a wider audience than your organization, see [Plugin structure and testing](/docs/plugins/build) and [Publish to the directory](/docs/directory/publish)
</Note>

To give the plugin to people you name, go to [Share a plugin with specific people](#share-a-plugin-with-specific-people). To reach the whole organization, go to [Publish a plugin to your organization](#publish-a-plugin-to-your-organization).

## Share a plugin with specific people

On a Team or Enterprise plan, you can give a plugin you created or uploaded to specific people in your organization yourself. You don't need an Owner, and nothing is published or reviewed.

### Choose how to distribute a plugin

You can get the plugin to specific people, to your organization's library, to someone outside your organization, or to a wider audience:

* **Share**: specific people in your organization get the plugin from you directly
* **Publish to org**: the plugin goes to your organization's library, where an Owner decides who can find and install it. See [Publish a plugin to your organization](#publish-a-plugin-to-your-organization)
* **The plugin file**: someone in another organization or on a personal plan adds the `.plugin` file or a zip of the plugin with **Add > Upload plugin**. It becomes a separate plugin on their account
* **A marketplace or the directory**: for a wider audience, put the plugin in a Git repository as a folder, as [Plugin structure and testing](/docs/plugins/build) describes, then share it through [your own marketplace](https://code.claude.com/docs/en/plugins/create-marketplace) or [the directory](/docs/directory/publish)

### Share the plugin

Sharing gives the people you name your plugin in their **Customize > Plugins** list, turned off until they turn it on. To share with specific people:

<Steps>
  <Step title="Open the plugin and select Share">
    Go to [**Customize > Plugins**](https://claude.ai/customize/plugins) in claude.ai or the desktop app and open the plugin. Select **Share** at the top of its page. The plugin's menu in your **Your plugins** list has the same **Share** item.
  </Step>

  <Step title="Add people">
    Add each person by name or email address, then confirm the share.
  </Step>
</Steps>

### What the people you share with get

**Share** reaches only members of your organization, and the people you share with can use the plugin but not change it:

* **Who you can share with**: members of the organization you're in. If you enter the email address of someone who isn't a member yet, they're invited to join your organization first, where your organization lets members send invitations. On Enterprise, where an Owner has turned on **Share with groups**, you can also add a user group. To reach someone in another organization or on a personal plan, send them the plugin file instead. **Share** has no option for the whole organization. To reach everyone, [publish the plugin to your organization](#publish-a-plugin-to-your-organization)
* **What they see**: a notice in claude.ai that you shared the plugin, and the plugin listed under **Shared with you** on the **Your plugins** tab of **Customize > Plugins**. It's turned off until they turn it on
* **What they do**: open the plugin and turn on its toggle. When the plugin includes something that runs on their computer, such as a local MCP server or a hook, Claude asks them to confirm first
* **What they can change**: nothing in the plugin. They can view it, turn it on or off, and use it. It stays in their list for as long as you share it
* **Your later edits**: people who turned the plugin on get your new version wherever they use Claude, including chat on the web
* **Connectors**: your connector sign-ins aren't shared. Each person adds or connects the plugin's connectors with their own account, as [Bundled connectors](/docs/plugins/overview#bundled-connectors) describes
* **The link**: **Copy link** in the share dialog copies a link to the plugin's page. Only people you've shared the plugin with can open it

### Stop sharing a plugin

When you stop sharing a plugin with someone, the plugin stops loading for them. To stop sharing, select **Share** again and remove the person from the list of people with access.

### If you can't share a plugin

**Share** appears only on a plugin you created or uploaded yourself, not on one you added from a marketplace or that your organization provides. On your own plugin, these are the cases where you can't share:

* **The share dialog says "Direct sharing is turned off for your organization"**: an Owner turned off **Skill sharing**, the setting that covers both skills and plugins. Ask an Owner to turn it on in [**Organization settings > Plugins & skills > Policy**](https://claude.ai/admin-settings/skills?tab=policy). Until then you can open **Share** to remove people, but you can't add anyone
* **Share is missing and Skills is turned off for your organization**: ask an Owner to turn on **Skills** on the same **Policy** tab
* **Share is missing and your organization's security scan blocked the plugin**: a blocked plugin can't be shared
* **You're on a personal plan**: sharing with specific people needs a Team or Enterprise plan. **Share** either offers an upgrade to a Team plan or doesn't appear

## Publish a plugin to your organization

Publishing puts your plugin in your organization's library, where an Owner decides who can find and install it. It's available on Team and Enterprise plans, and whether you can do it depends on the **Publishing** setting an Owner has chosen for your organization.

Sharing reaches only the people you name and needs no approval. Publishing can reach the whole organization, and under the **Requires review** setting it waits for an Owner to approve it.

To publish, open the plugin from **Customize > Plugins** and select **Publish to org** at the top of its page. This is what happens next under each **Publishing** setting:

* **Requires review**: you submit the plugin for review and propose how it installs for members: **Available to install**, **Installed by default**, or **Required**. The version you submit is frozen, so edits you make afterward aren't part of the request. The reviewer sees your proposal and can change it before approving. An Owner approves or denies it in [**Organization settings > Plugins & skills > Requests**](https://claude.ai/admin-settings/skills?tab=requests), and you can't approve your own submission. You get the decision by email, with the reviewer's reason if it's denied
* **Open**: the plugin is published without review. Where your organization scans what members publish, it goes live after the security scan passes
* **Off**: your organization doesn't accept plugins from members, and **Publish to org** doesn't appear on your plugin

On a Team plan, the **Publishing** setting is **Open** unless an Owner has changed it. [Review plugins that members publish](/docs/plugins/admin#review-plugins-that-members-publish) lists the default for each plan.

You see the result on the plugin's own page, which shows whether the submission is waiting for review, denied, or published:

* **While it's waiting**: you can withdraw it from the plugin's page
* **If it's denied**: the page shows the date and the reviewer's reason, and **Publish to org** is available again so that you can revise the plugin and submit a new request
* **After a version is published**: later edits reach your organization only when you publish again

## Next steps

* [Create a plugin with Claude](/docs/plugins/create-with-claude): make a plugin in claude.ai or the desktop app with Claude's help
* [Manage plugins for your organization](/docs/plugins/admin): if you're an Owner, turn sharing and publishing on or off for members
* [Plugin structure and testing](/docs/plugins/build): write the plugin as a folder for a marketplace or the directory

plugins/submit Changed · +162 / -82 lines

# Submit your plugin ## Before you submit a plugin ## Submit a plugin ### Submission limits and duplicates ## After you submit a plugin ### Fix a failed version ### Publish a passing version ## Update a published plugin ### Change the tracked branch or tag ## Withdraw or delist a plugin ## Next steps # Submitting your plugin ## Getting your plugin to users ## Plugin Directory: Community vs. Anthropic Verified ## What makes a good plugin ### Guiding Claude through MCP setup ### Using safe MCP connectors in plugins ## Directory terms & conditions ## Security ## Submitting your plugin ### Before you start

skills/how-to Changed · +602 / -105 lines

# Create custom skills ## Decide what skill to create ## Create a `SKILL.md` file ### Write the instructions ## Add resources ## Add scripts ## Package your skill ## Test your skill ### In Claude Code ### Measure whether the skill improves the output ## Share or package your skill ## Next steps # Creating custom skills ## Creating a `SKILL.md` file ### Markdown body ## Adding resources ## Adding scripts ## Packaging your skill ## Testing your skill ## Security considerations ## Related topics

The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.

skills/overview Changed · +54 / -34 lines

## Understand how skills work ## Find, turn on, and use skills ## Compare skills with other features ## Use skills beyond Claude ## Next steps ## Availability ## How skills work ## Skills vs. other features ## Open standard ## Related topics

third-party/claude-desktop/bootstrap Changed · +9 / -1 lines

third-party/claude-desktop/configuration Changed · +5 / -5 lines

This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.

third-party/claude-desktop/gateway Changed · +4 / -4 lines