- If you want to make a plugin from a conversation without writing files, see Create a plugin with Claude
- If you want to distribute a plugin only inside your own organization, see Roll out a plugin to your whole organization
- If you want to look up the folder layout, the manifest fields, or what each surface loads, see Plugin structure and testing
Before you create the plugin
Check that you have each of these before you create the plugin:- Claude Code: install Claude Code. 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 namedexpense-reports for a fictional finance product whose MCP server is at mcp.example.com. Replace the names and values with your own.
1
Write the manifest
Create a folder named People install and refer to the plugin by its
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:name. Use lowercase words joined by hyphens, make the name specific to your product, and never change it after release. Manifest and plugin name lists the directory’s checks on the name.2
Add a skill
Create Claude decides when to load the skill from the
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:description line, so write it as the situations a user would be in. Create custom skills covers the frontmatter fields, resource files, scripts, and testing.3
Add an MCP connector
Skip this step if your plugin has only a skill. If your product has a remote MCP server, create There is no server at
.mcp.json at the plugin root and reference the server by URL: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 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.4
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 lists what validation checks.This README covers those three points for the example plugin:5
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.Test the plugin in Claude Code
Load the plugin from your working copy before you push it. From the folder that containsexpense-reports, start a Claude Code session with the plugin loaded:
/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.
Validate the plugin
Runclaude plugin validate on the folder to catch syntax and schema errors on your machine before you push:
✔ 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 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
Push the plugin to GitHub
The directory reads plugins from repositories on github.com, so the plugin folder goes in a GitHub repository.1
Create the repository
Create an empty repository on github.com for the plugin. The repository must be public before the listing goes live.
2
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.3
Commit and push
From inside the The repository’s page on github.com now shows
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:.claude-plugin/, skills/, and the other plugin files at the repository root.Submit your own plugin
Theexpense-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: select Submit new, choose Plugin bundle, and follow 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. Who can submit to the directory has the plan and role requirements.
Next steps
- Plugin structure and testing: look up the folder layout and manifest fields, and test on claude.ai and in Cowork
- Plugin pre-submission checklist: fix each validation and scan finding before you submit
- Submit a plugin: fill in each portal field, then publish and update the listed plugin
- Track your submission: check what your submission’s status means and who acts next
- Plugin feature support across platforms: check which of the plugin’s components load in chat, Cowork, and Claude Code
claude plugin eval: write eval cases and compare the plugin’s results against a run without the plugin