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

> Learn how to publish skills to the Claude Marketplace with this step by step guide. Validate, package, register, and add your skill to Claude Code effortlessly.

- Repository: [Anthropic/skills](https://github.com/anthropics/skills)
- Tags: how-to-guide
- Published: 2026-02-19

---

**To publish skills to the Claude Marketplace, validate and package your skill using the [`package_skill.py`](https://github.com/anthropics/skills/blob/main/package_skill.py) script, register it in the repository's [`.claude-plugin/marketplace.json`](https://github.com/anthropics/skills/blob/main/.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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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:

```bash

# 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`](https://github.com/anthropics/skills/blob/main/package_skill.py) script internally calls `quick_validate.validate_skill` from [`skills/skill-creator/scripts/quick_validate.py`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/scripts/quick_validate.py) to verify compliance with [`spec/agent-skills-spec.md`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/.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:

```json
{
  "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:

```text
/plugin marketplace add anthropics/skills

```

Claude indexes the repository, reads [`.claude-plugin/marketplace.json`](https://github.com/anthropics/skills/blob/main/.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:

```text
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`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/scripts/package_skill.py), which runs `quick_validate.validate_skill` against the [`spec/agent-skills-spec.md`](https://github.com/anthropics/skills/blob/main/spec/agent-skills-spec.md) schema and outputs a `.skill` zip file.
- **Register** your skill in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/skills/blob/main/.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`](https://github.com/anthropics/skills/blob/main/package_skill.py) script calls `quick_validate.validate_skill` from [`skills/skill-creator/scripts/quick_validate.py`](https://github.com/anthropics/skills/blob/main/skills/skill-creator/scripts/quick_validate.py), which validates your [`SKILL.md`](https://github.com/anthropics/skills/blob/main/SKILL.md) front-matter and folder structure against the [`spec/agent-skills-spec.md`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/.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`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/SKILL.md), source code, and assets during development. While the [`marketplace.json`](https://github.com/anthropics/skills/blob/main/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`](https://github.com/anthropics/skills/blob/main/.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.