Publishing Skills

Learn how to structure, validate, and publish skills to the registry.

Skill Structure#

A skill is a folder containing a manifest file and one or more content files. Here is a typical layout:

my-skill/
  SKILL.md            # Manifest (YAML frontmatter) + skill instructions
  examples/
    basic-usage.md    # Example files referenced by instructions
    advanced.md
  README.md           # Human-readable documentation (not installed)

The entry point is the main file that Claude Code reads when the skill is loaded. By default this is SKILL.md, which serves as both the manifest (via YAML frontmatter) and the main instructions file.

Manifest (SKILL.md)#

The SKILL.md file serves as both the manifest and the main instructions file. Metadata is defined in the YAML frontmatter block at the top of the file.

---
# Required
name: code-reviewer              # 1-64 characters
description: >
  Automated code review skill     # Max 1024 characters
  that checks for common issues

# Registry fields
version: "1.0.0"                 # Semantic version
scope: backend                   # Team scope for publishing
tags:                            # Up to 10 tags
  - code-review
  - linting
  - best-practices

# Claude Code skill fields
allowed-tools: Read,Grep,Glob    # Tools the skill can use
user-invocable: true             # Show in /slash command menu
argument-hint: "<file-path>"     # Hint shown in command palette
model: sonnet                    # Preferred model
context: project                 # Context scope

# Optional
license: MIT                     # SPDX license identifier
---

# Code Reviewer

Your skill instructions go here...

The name field must be in slug format (lowercase alphanumeric with hyphens, 1-64 characters). Combined with the team scope, this forms the full skill identifier (e.g., @backend/code-reviewer).

Publishing Workflow#

Publishing a skill involves scaffolding, editing, validating, and pushing to the registry.

1. Scaffold a new skill:

csreg init my-skill

2. Edit your skill files — Update SKILL.md with your metadata and write your instructions in the entry point file.

3. Validate your skill:

csreg validate

Validation checks the manifest schema, verifies the entry file exists, and enforces size limits.

4. Publish to the registry:

csreg push

The push command accepts the following flags:

csreg push [directory]
  --all    # Push all skills in .claude/skills/

Versioning#

Skills follow semantic versioning (semver). Version numbers take the form MAJOR.MINOR.PATCH with optional prerelease tags (e.g., 2.0.0-beta.1).

• MAJOR — Increment for breaking changes to the skill's behavior or interface.
• MINOR — Increment for new functionality that is backward-compatible.
• PATCH — Increment for backward-compatible bug fixes and improvements.

Each version has a status that follows this lifecycle:

• draft — Work in progress. Not available for installation. Can be promoted to published.
• published — Available for installation. Can be yanked if needed.
• yanked — Deprecated and hidden from new installs. Existing installs are not affected. Cannot be reversed.

Channels#

Channels are named pointers that map to a specific published version. They allow consumers to track a stability tier rather than pinning to an exact version number.

The latest channel is special: it is automatically updated every time a new version is published and cannot be deleted. You can also create custom channels for different release tracks:

• latest — Auto-updated on every publish. Cannot be deleted.
• stable — Manually pointed to a tested, production-ready version.
• canary — Pointed to pre-release or experimental versions.

Channels can be managed via the registry API.

Visibility#

Skill visibility controls who can discover, read, and write to a skill. There are three levels: