Build your first plugin changedplugins/quickstart
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 20 Oct 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+91added
Lines−95removed
From line
6
where the diff opens
First seen
25 Sep 2026
this site's first read of the page
Recorded edits4to this page, all time
The whole hunk
from line 6, old and new numbered
/
from line 6
66
77This 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.
88
9<Note>
10 * If you want to make a plugin from a conversation without writing files, see [Create a plugin with Claude](/docs/plugins/create-with-claude)
11 * 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)
12 * 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)
13</Note>
9> [!NOTE]
10>
11> * If you want to make a plugin from a conversation without writing files, see [Create a plugin with Claude](/docs/plugins/create-with-claude)
12> * 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)
13> * 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)
1414
1515## Before you create the plugin
1616
from line 23
2323
2424The 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.
2525
26<Steps>
27 <Step title="Write the manifest">
28 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.
26**1. Write the manifest**
2927
30 The example has the fields that every surface and the directory read:
28Create 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.
3129
32 ```json theme={null}
33 {
34 "name": "expense-reports",
35 "displayName": "Expense Reports",
36 "version": "1.0.0",
37 "description": "File, track, and approve expense reports from a conversation, using your finance system's connector and your company's approval rules.",
38 "author": { "name": "Example Corp", "url": "https://example.com" },
39 "license": "MIT"
40 }
41 ```
30The example has the fields that every surface and the directory read:
4231
43 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.
44 </Step>
32```json theme={null}
33{
34 "name": "expense-reports",
35 "displayName": "Expense Reports",
36 "version": "1.0.0",
37 "description": "File, track, and approve expense reports from a conversation, using your finance system's connector and your company's approval rules.",
38 "author": { "name": "Example Corp", "url": "https://example.com" },
39 "license": "MIT"
40}
41```
4542
46 <Step title="Add a skill">
47 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:
43People 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.
4844
49 ```markdown theme={null}
50 ---
51 name: file-expense
52 description: File an expense report. Use when the user mentions a receipt, reimbursement, or expense, or asks to submit spending for approval.
53 ---
45**2. Add a skill**
5446
55 To file an expense:
47Create `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:
5648
57 1. Ask for the receipt if the user hasn't attached one, and read the amount, date, merchant, and currency from it.
58 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.
59 3. If the amount is over the user's approval limit (check with `get_policy`), add their manager as approver before submitting.
60 4. Reply with the report number and its approval status. Don't paste the full API response.
61 ```
49```markdown theme={null}
50---
51name: file-expense
52description: File an expense report. Use when the user mentions a receipt, reimbursement, or expense, or asks to submit spending for approval.
53---
6254
63 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.
64 </Step>
55To file an expense:
6556
66 <Step title="Add an MCP connector">
67 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:
571. Ask for the receipt if the user hasn't attached one, and read the amount, date, merchant, and currency from it.
582. Call the expenses connector's `create_report` tool with those fields. Default the category from the merchant type; ask only if it's ambiguous.
593. If the amount is over the user's approval limit (check with `get_policy`), add their manager as approver before submitting.
604. Reply with the report number and its approval status. Don't paste the full API response.
61```
6862
69 ```json theme={null}
70 {
71 "mcpServers": {
72 "expenses": {
73 "type": "http",
74 "url": "https://mcp.example.com/mcp"
75 }
76 }
63Claude 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.
64
65**3. Add an MCP connector**
66
67Skip 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:
68
69```json theme={null}
70{
71 "mcpServers": {
72 "expenses": {
73 "type": "http",
74 "url": "https://mcp.example.com/mcp"
7775 }
78 ```
76 }
77}
78```
7979
80 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.
80There 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.
8181
82 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.
83 </Step>
82Don'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.
8483
85 <Step title="Write the README">
86 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.
84**4. Write the README**
8785
88 This README covers those three points for the example plugin:
86Create `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.
8987
90 ```markdown theme={null}
91 # Expense Reports
88This README covers those three points for the example plugin:
9289
93 File, track, and approve expense reports from a conversation with Claude.
90```markdown theme={null}
91# Expense Reports
9492
95 ## Use it
93File, track, and approve expense reports from a conversation with Claude.
9694
97 Attach a receipt and ask Claude to file it. Claude reads the amount, date,
98 and merchant, files the report through the Expense Reports connector, and
99 replies with the report number. Ask what's waiting on you to list the
100 reports that need your approval.
95## Use it
10196
102 ## Data
97Attach a receipt and ask Claude to file it. Claude reads the amount, date,
98and merchant, files the report through the Expense Reports connector, and
99replies with the report number. Ask what's waiting on you to list the
100reports that need your approval.
103101
104 The plugin sends receipt details and report fields to your Example Corp
105 account through mcp.example.com. It stores nothing itself.
106 ```
107 </Step>
102## Data
108103
109 <Step title="Check the license">
110 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.
111 </Step>
112</Steps>
104The plugin sends receipt details and report fields to your Example Corp
105account through mcp.example.com. It stores nothing itself.
106```
113107
108**5. Check the license**
109
110The 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.
111
114112## Test the plugin in Claude Code
115113
116114Load 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:
from line 145
147145
148146The directory reads plugins from repositories on github.com, so the plugin folder goes in a GitHub repository.
149147
150<Steps>
151 <Step title="Create the repository">
152 Create an empty repository on github.com for the plugin. The repository must be public before the listing goes live.
153 </Step>
148**1. Create the repository**
154149
155 <Step title="Remove system files">
156 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.
157 </Step>
150Create an empty repository on github.com for the plugin. The repository must be public before the listing goes live.
158151
159 <Step title="Commit and push">
160 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:
152**2. Remove system files**
161153
162 ```bash theme={null}
163 git init -b main
164 git add .
165 git commit -m "Add the expense-reports plugin"
166 git remote add origin https://github.com/example-corp/expense-reports.git
167 git push -u origin main
168 ```
154Remove `.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.
169155
170 The repository's page on github.com now shows `.claude-plugin/`, `skills/`, and the other plugin files at the repository root.
171 </Step>
172</Steps>
156**3. Commit and push**
157
158From 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:
159
160```bash theme={null}
161git init -b main
162git add .
163git commit -m "Add the expense-reports plugin"
164git remote add origin https://github.com/example-corp/expense-reports.git
165git push -u origin main
166```
167
168The repository's page on github.com now shows `.claude-plugin/`, `skills/`, and the other plugin files at the repository root.
173169
174170## Submit your own plugin
175171
No line in this hunk matches that.