Plugin structure and testing changedplugins/build
Nearest release: v2.1.284, published 16 hours after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 28 Sep 2026 00:41 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 22 Oct 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+17added
Lines−17removed
From line
4
where the diff opens
First seen
25 Sep 2026
this site's first read of the page
Recorded edits5to this page, all time
The whole hunk
from line 4, old and new numbered
/
from line 4
44
55A plugin is a folder that packages skills, MCP connectors, commands, and agents, in any combination, so that people add them together. This page is the reference for that folder: what each file is and contains, the manifest fields every app reads, how an MCP connector and its skill fit together, and how to test the plugin on claude.ai, in Cowork, and in Claude Code.
66
7[Build your first plugin](/docs/plugins/quickstart) walks you through making one end to end.
7[Build your first plugin](/docs/plugins/quickstart.md) walks you through making one end to end.
88
99> [!NOTE]
1010>
11> * If you want a plugin for your own use without writing files, see [Create a plugin with Claude](/docs/plugins/create-with-claude), which makes one from a conversation
11> * If you want a plugin for your own use without writing files, see [Create a plugin with Claude](/docs/plugins/create-with-claude.md), which makes one from a conversation
1212> * If you're building for Claude Code only, see its [plugin authoring docs](https://code.claude.com/docs/en/plugins/create). Claude Code supports more component types than the other surfaces, and those docs are the full reference for anything Claude Code-only
13> * If you're deciding which pieces your plugin needs, see [Decide what to include in your plugin](/docs/connectors/building/what-to-build)
13> * If you're deciding which pieces your plugin needs, see [Decide what to include in your plugin](/docs/connectors/building/what-to-build.md)
1414
1515## Lay out the plugin folder
1616
from line 32
3232
3333Selected file
3434
35The manifest identifies the plugin to every app and to Anthropic's directory. Without any `plugin.json`, the directory accepts only a folder whose `skills/` directory holds at least one `<name>/SKILL.md`, and lists that plugin for Claude Code only, not for claude.ai or Cowork. To publish the plugin in Anthropic's directory you also need [a README and a license](/docs/plugins/pre-submission-checklist#readme-and-license); select those files in the tree to see what each needs.
35The manifest identifies the plugin to every app and to Anthropic's directory. Without any `plugin.json`, the directory accepts only a folder whose `skills/` directory holds at least one `<name>/SKILL.md`, and lists that plugin for Claude Code only, not for claude.ai or Cowork. To publish the plugin in Anthropic's directory you also need [a README and a license](/docs/plugins/pre-submission-checklist.md#readme-and-license); select those files in the tree to see what each needs.
3636
3737Its `name` is the plugin's permanent identity: people install and refer to the plugin by this value, so make it specific to your product and never change it after release. Change `displayName` when you want a different label.
3838
from line 66
66663. Reply with the report number and its approval status.
6767```
6868
69A skill folder can hold [supporting files](/docs/skills/how-to#add-resources) that are too detailed for `SKILL.md`:
69A skill folder can hold [supporting files](/docs/skills/how-to.md#add-resources) that are too detailed for `SKILL.md`:
7070
7171<ul>
7272 <li>`references/` for documentation Claude reads when needed</li>
from line 88
8888
8989A skill can include scripts in a `scripts/` folder next to `SKILL.md`.
9090
91In `SKILL.md`, refer to a script by its path under `${CLAUDE_SKILL_DIR}`, for example `python3 ${CLAUDE_SKILL_DIR}/scripts/total.py receipts.csv`. [Add scripts](/docs/skills/how-to#add-scripts) explains how each app resolves that path.
91In `SKILL.md`, refer to a script by its path under `${CLAUDE_SKILL_DIR}`, for example `python3 ${CLAUDE_SKILL_DIR}/scripts/total.py receipts.csv`. [Add scripts](/docs/skills/how-to.md#add-scripts) explains how each app resolves that path.
9292
9393This script totals the amounts in a CSV file of receipts:
9494
from line 130
130130}
131131```
132132
133A plugin loads without a README, but you need one to publish it: Anthropic's directory shows the README as the listing's description, and [validation](/docs/plugins/pre-submission-checklist#readme-and-license) blocks a submission that has none.
133A plugin loads without a README, but you need one to publish it: Anthropic's directory shows the README as the listing's description, and [validation](/docs/plugins/pre-submission-checklist.md#readme-and-license) blocks a submission that has none.
134134
135135Write at least 40 words, not counting words inside code blocks, and say what the plugin does, how to use it, and what data it sends.
136136
from line 154
154154account through mcp.example.com. It stores nothing itself.
155155```
156156
157A plugin loads without a license, but you need one to publish it: Anthropic's directory doesn't list a plugin until it has a license, and [validation](/docs/plugins/pre-submission-checklist#readme-and-license) blocks a submission that has neither a `LICENSE` file nor a `license` field.
157A plugin loads without a license, but you need one to publish it: Anthropic's directory doesn't list a plugin until it has a license, and [validation](/docs/plugins/pre-submission-checklist.md#readme-and-license) blocks a submission that has neither a `LICENSE` file nor a `license` field.
158158
159159Add a `LICENSE` file to the plugin folder, or set `license` in `plugin.json`.
160160
from line 172
172172* **A local MCP server**, one the app starts as a command, loads in Claude Code and in Cowork sessions that run on the person's computer; chat ignores it
173173* **A top-level `bin/` directory** stops claude.ai and Cowork from installing the plugin at all
174174
175[Plugin support by app](/docs/plugins/platform-support#compare-component-support-by-app) has the full table, including LSP servers, output styles, and `${user_config.*}` references, and compares where installs are stored and what an organization controls on each app.
175[Plugin support by app](/docs/plugins/platform-support.md#compare-component-support-by-app) has the full table, including LSP servers, output styles, and `${user_config.*}` references, and compares where installs are stored and what an organization controls on each app.
176176
177177### Start from an example
178178
from line 182
182182
183183## Write the plugin
184184
185The examples in this section build a plugin named `expense-reports` for a fictional finance product whose MCP server is at `mcp.example.com`. If you plan to submit the plugin to Anthropic's directory, keep the [plugin pre-submission checklist](/docs/plugins/pre-submission-checklist) open while you write: the developer portal validates the manifest, README, license, and scripts when you submit, and building with those checks in mind means validation passes the first time.
185The examples in this section build a plugin named `expense-reports` for a fictional finance product whose MCP server is at `mcp.example.com`. If you plan to submit the plugin to Anthropic's directory, keep the [plugin pre-submission checklist](/docs/plugins/pre-submission-checklist.md) open while you write: the developer portal validates the manifest, README, license, and scripts when you submit, and building with those checks in mind means validation passes the first time.
186186
187187### Write the manifest
188188
from line 223
223223}
224224```
225225
226On claude.ai and in Cowork, that 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.
226On claude.ai and in Cowork, that entry is listed on the plugin's **Connectors** tab, where the user [adds or connects it](/docs/plugins/overview.md#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.
227227
228228Don't put API keys or other secrets in this file, because every person who installs the plugin receives its files. If your server is already listed in the directory, use the same URL here, so that someone who has both your connector and your plugin sees one set of tools rather than two.
229229
from line 243
2432434. Reply with the report number and its approval status. Don't paste the full API response.
244244```
245245
246Claude decides when to load the skill from the `description` line, so write it as the situations a user would be in, not as a summary of the file. [Create custom skills](/docs/skills/how-to) covers the frontmatter fields, resource files, scripts, and testing.
246Claude decides when to load the skill from the `description` line, so write it as the situations a user would be in, not as a summary of the file. [Create custom skills](/docs/skills/how-to.md) covers the frontmatter fields, resource files, scripts, and testing.
247247
248248## Test the plugin on each surface
249249
from line 258
258258 5. If your plugin has agents, start a Cowork task to confirm they load.
259259* **A team testing together**: push the folder to a Git repository set up as a [marketplace](https://code.claude.com/docs/en/plugins/create-marketplace), and have each tester add it from **Customize > Plugins > Add > Add marketplace** with the repository URL instead, so everyone installs the same copy
260260
261Loading the plugin shows that its parts appear. To measure whether its skills improve Claude's output, write eval cases and run [`claude plugin eval`](https://code.claude.com/docs/en/plugin-evals) in Claude Code, which grades the results and compares them against a run without the plugin. To test one skill by itself on any surface, see [Measure whether the skill improves the output](/docs/skills/how-to#measure-whether-the-skill-improves-the-output).
261Loading the plugin shows that its parts appear. To measure whether its skills improve Claude's output, write eval cases and run [`claude plugin eval`](https://code.claude.com/docs/en/plugin-evals) in Claude Code, which grades the results and compares them against a run without the plugin. To test one skill by itself on any surface, see [Measure whether the skill improves the output](/docs/skills/how-to.md#measure-whether-the-skill-improves-the-output).
262262
263Before you submit the plugin to the directory, run `claude plugin validate ./expense-reports`, then select **Validate** in the [developer portal](https://claude.ai/directory/manage). The portal runs every validation check, and [Run the checks before you submit](/docs/plugins/pre-submission-checklist#run-the-checks-before-you-submit) explains each result.
263Before you submit the plugin to the directory, run `claude plugin validate ./expense-reports`, then select **Validate** in the [developer portal](https://claude.ai/directory/manage). The portal runs every validation check, and [Run the checks before you submit](/docs/plugins/pre-submission-checklist.md#run-the-checks-before-you-submit) explains each result.
264264
265265When something is missing on one surface and present on another, check it against [Check what each app loads](#check-what-each-app-loads) before debugging. An agent that never appears in chat, or a local server that chat doesn't start, is the surface behaving as designed.
266266
from line 272
272272
273273Once the plugin works, you can distribute it through your organization, your own marketplace, or the directory:
274274
275* [Manage plugins for your organization](/docs/plugins/admin): on Team and Enterprise plans, an Owner can make the plugin available or installed by default for members
275* [Manage plugins for your organization](/docs/plugins/admin.md): on Team and Enterprise plans, an Owner can make the plugin available or installed by default for members
276276* [Create a marketplace](https://code.claude.com/docs/en/plugins/create-marketplace): list the plugin in a Git repository's `marketplace.json`, which anyone you give the URL to can add from **Customize > Plugins** or the Claude Code command line
277* [Publish to the directory](/docs/directory/publish): submit the plugin from the [developer portal](https://claude.ai/directory/manage) so people on Pro, Max, Team, and Enterprise plans can find and add it on claude.ai and in Cowork, and use it in Claude Code. Anyone on a paid plan can submit without applying to a partner program first; on Team and Enterprise, an Owner submits
277* [Publish to the directory](/docs/directory/publish.md): submit the plugin from the [developer portal](https://claude.ai/directory/manage) so people on Pro, Max, Team, and Enterprise plans can find and add it on claude.ai and in Cowork, and use it in Claude Code. Anyone on a paid plan can submit without applying to a partner program first; on Team and Enterprise, an Owner submits
278278
No line in this hunk matches that.