How to Publish Skills to the Claude Marketplace: A Step-by-Step Guide

To publish skills to the Claude Marketplace, validate and package your skill using the package_skill.py script, register it in the repository's .claude-plugin/marketplace.json manifest, and add the repository to Claude Code using the /plugin marketplace add command.

The anthropics/skills repository provides the complete toolchain and infrastructure necessary to publish skills to the Claude Marketplace. This guide walks through the exact workflow used by the Anthropic team, referencing specific source files like skills/skill-creator/scripts/package_skill.py and the marketplace manifest configuration.

Validate and Package Your Skill

Before publishing, you must validate that your skill meets the Agent Skills specification and package it into a distributable format. The repository includes skills/skill-creator/scripts/package_skill.py, which automates both validation and packaging by calling quick_validate.validate_skill and creating a .skill zip archive.

Running the Packaging Script

Execute the script from the repository root, providing the path to your skill directory:

# Basic usage

scripts/package_skill.py path/to/your/skill

# Specify custom output directory

scripts/package_skill.py path/to/your/skill ./dist

This creates a .skill zip file (e.g., your-skill.skill) containing your complete directory structure, ready for distribution.

Understanding the Validation Process

The package_skill.py script internally calls quick_validate.validate_skill from skills/skill-creator/scripts/quick_validate.py to verify compliance with spec/agent-skills-spec.md. The validator checks:

• SKILL.md front-matter: Ensures required metadata fields and schema compliance
• Folder layout: Validates that the directory structure matches the Agent Skills specification

If validation fails, the script outputs specific error messages indicating which schema requirements are violated. Fix the reported issues in your SKILL.md or directory layout and rerun the packaging command.

Register Your Skill in the Marketplace Manifest

Once validated, you must register the skill in the repository's marketplace configuration file located at .claude-plugin/marketplace.json. This manifest tells Claude which plugins are available and maps them to specific skill directories.

Structuring the marketplace.json Entry

The manifest uses a JSON structure where each plugin defines a collection of skills. Add your skill to an existing plugin or create a new entry:

{
  "plugins": [
    {
      "name": "my-custom-skills",
      "description": "Internal automation tools for data processing",
      "source": "./",
      "strict": false,
      "skills": [
        "./skills/my-custom-skill",
        "./skills/another-skill"
      ]
    }
  ]
}

Key fields include:

• name: Unique identifier for the plugin collection
• skills: Array of paths to skill directories relative to the repository root
• strict: Boolean flag controlling validation strictness

Commit and push these changes to the main branch. Claude indexes the repository from the default branch when adding it to an environment.

Add the Repository to Claude

With your skill validated and registered in the manifest, the final step is adding the repository to a Claude environment using the marketplace command.

Installing and Using Your Skill

In Claude Code or the Claude web interface, execute:

/plugin marketplace add anthropics/skills

Claude indexes the repository, reads .claude-plugin/marketplace.json, and registers each defined plugin. Users can then browse and install your skill:

1. Navigate to Plugins → Browse and install plugins
2. Select anthropic-agent-skills (or your custom plugin name)
3. Choose the specific skill collection (e.g., my-custom-skills)
4. Click Install now

Once installed, invoke the skill directly in conversation:

Use the my-custom-skill to generate a weekly sales summary from ./reports/

Summary

• Validate and package skills using skills/skill-creator/scripts/package_skill.py, which runs quick_validate.validate_skill against the spec/agent-skills-spec.md schema and outputs a .skill zip file.
• Register your skill in .claude-plugin/marketplace.json by adding its directory path to the skills array within a plugin definition.
• Distribute by running /plugin marketplace add anthropics/skills in Claude Code, then installing the specific plugin containing your skill through the Claude interface.

Frequently Asked Questions

How do I troubleshoot validation errors when packaging a skill?

The package_skill.py script calls quick_validate.validate_skill from skills/skill-creator/scripts/quick_validate.py, which validates your SKILL.md front-matter and folder structure against the spec/agent-skills-spec.md specification. If validation fails, the script outputs specific error messages indicating which schema requirements are violated. Review the error details, fix the reported issues in your skill metadata or directory layout, and rerun the packaging command.

Can I publish multiple skills as a single plugin?

Yes. The .claude-plugin/marketplace.json manifest supports grouping multiple skills under a single plugin entry. In the skills array, include paths to multiple skill directories relative to the repository root. For example, you can bundle ./skills/xlsx, ./skills/docx, and ./skills/pdf under a single "document-skills" plugin, allowing users to install them together rather than individually.

What is the difference between the .skill file and the skill directory?

The .skill file is a distributable zip archive generated by package_skill.py that contains your entire skill directory structure in a compressed format suitable for distribution. The skill directory is the uncompressed folder containing your SKILL.md, source code, and assets during development. While the marketplace.json manifest references skill directories by path, the .skill file serves as the packaged artifact for external distribution or backup purposes.

Do I need to commit the packaged .skill files to the repository?

No, you do not need to commit the generated .skill files to version control. The .claude-plugin/marketplace.json manifest references skill directories (e.g., ./skills/my-custom-skill), not the packaged zip files. Claude handles the skill loading directly from these directories when the repository is indexed. Add *.skill to your .gitignore file to exclude these build artifacts from your commits.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}