Run the checks before you submit
Checking a plugin before you submit it takes three steps:- Optional: check the plugin on your machine with Claude Code’s
claude plugin validatecommand, which catches syntax and schema errors before you push - Validate in the developer portal, which runs every directory check in the tables on this page
- Read the result, fix every finding that the report marks Blocking, and then submit
Check the plugin on your machine (optional)
If you have Claude Code, 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:✔ 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 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.1
Start a submission
Open the developer portal and select Submit new.
2
Choose Plugin bundle
When the portal asks What would you like to submit?, select Plugin bundle.
3
Enter the repository
On the Source step, enter the repository. Submit your plugin describes each field.
4
Validate
Select Validate. The report lists each finding with its result and, for many findings, a fix.
5
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.
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
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.
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 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 describes.
README and license
The directory shows your README as the listing’s description and requires a license before it lists the plugin.Files in the plugin folder
The file checks apply to every file in the plugin folder, including images and documents.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.
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 runwith--lockedor--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.jsonbesidepackage-lock.json,npm-shrinkwrap.json,bun.lock, orbun.lockbin the root of the plugin folder is held, because Claude Code installs the packages in that lockfile 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 thatSKILL.mdonly 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
Hooks, skills, commands, and agents
The component checks confirm that Claude Code can load each hook, skill, command, and agent file in the plugin.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 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 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:1
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 runs that comparison for the whole plugin in Claude Code, and Measure whether the skill improves the output covers one skill at a time.2
Load the plugin on each surface
Load the plugin on each surface your users will use, as Test the plugin on each surface describes.
Next steps
- Submit your plugin: enter the repository in the developer portal, follow the review, and publish
- Publish to the directory: confirm your plan and role can submit, and see what Anthropic’s review involves