Skip to main content
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. 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.

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 named expense-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 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:
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 lists the directory’s checks on the name.
2

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:
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 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 .mcp.json at the plugin root and reference the server by URL:
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 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 contains expense-reports, start a Claude Code session with the plugin loaded:
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.

Validate the plugin

Run claude plugin validate on the folder to catch syntax and schema errors on your machine before you push:
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 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 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.
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 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:
The repository’s page on github.com now shows .claude-plugin/, skills/, and the other plugin files at the repository root.

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: 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