Publishing Skills

Create, version, and push SKILL.md files to the SkillReg registry. Learn about semantic versioning, access control, and publishing workflows.

Initialize a Skill

The skillreg init command scaffolds a new skill directory with a ready-to-edit SKILL.md template. If you omit the name, the CLI will prompt you interactively.

skillreg init[name]

Create a new skill directory with a SKILL.md template.

Flag	Description	Default
--description <text>	Short description of the skill	—
--author <name>	Author name	—
--tags <tags>	Comma-separated list of tags	—

Terminal

$ skillreg init react-testing

  ✓ Created skill: react-testing/
    └── SKILL.md

  Next steps:
    1. Edit react-testing/SKILL.md
    2. skillreg push react-testing --org <your-org>

The generated SKILL.md contains YAML frontmatter with metadata and placeholder sections for instructions and examples:

react-testing/SKILL.md

---
name: "react-testing"
description: ""
metadata:
  author: ""
  version: "0.1.0"
---

# react-testing

## Instructions

[Add your skill instructions here]

## Examples

[Add usage examples here]

Push a Skill

The skillreg push command validates your skill directory, packages its contents into a tarball, and uploads it to the registry. The process works in three steps:

Validate — Checks for a valid SKILL.md, verifies the skill name format, and ensures the version is valid semver.
Package — Strips any injected environment variable sections from .md files (so secrets are never uploaded), then creates a .tar.gz archive with a SHA-256 checksum.
Upload — Sends the tarball to the registry under the specified organization, version, and distribution tag.

skillreg push<directory>

Package and upload a skill to the registry.

Flag	Description	Default
--org <slug>	Organization slug	—
--name <name>	Override skill name (defaults to directory name)	—
--version <version>	Override version (reads from SKILL.md if omitted)	—
--bump <type>	Auto-bump version: patch, minor, major	—
--tag <tag>	Distribution tag	latest
--dry-run	Show what would be pushed without uploading	—

Terminal

# Basic push
$ skillreg push react-testing --org my-team

  Packaging react-testing@0.1.0...
  ✓ Pushed react-testing@0.1.0
    SHA256: a1b2c3d4...

# Push with auto-bump
$ skillreg push react-testing --org my-team --bump minor

  Version bumped: 0.1.0 → 0.2.0
  Packaging react-testing@0.2.0...
  ✓ Pushed react-testing@0.2.0
    SHA256: e5f6a7b8...

# Dry-run to preview
$ skillreg push react-testing --org my-team --dry-run

  [dry-run] Would push react-testing@0.2.0 to @my-team
    Tag: latest
    Files: 1
    Size: 0.8 KB
    SHA256: e5f6a7b8...

Skill name consistency

The name field in your SKILL.md frontmatter should match the name used during push (the directory name, or the value passed via --name). A mismatch will produce a warning.

Push All Skills

The skillreg push-all command pushes every local skill to the registry in a single operation. It scans your configured skills directory for subdirectories containing a SKILL.md file and pushes each one.

skillreg push-all

Push all local skills to the registry at once.

Flag	Description	Default
--org <slug>	Organization slug	—

Symlinked skills are excluded

Symlinked directories are automatically skipped during push-all. These are typically third-party skills installed via skillreg pull, which should not be re-published under your organization.

Version Bumping

Use the --bump flag with skillreg push to automatically increment the version before publishing. The CLI reads the current version from SKILL.md, bumps it, and writes the new version back to the frontmatter.

--bump patch — 0.1.0 becomes 0.1.1 (bug fixes, minor changes)
--bump minor — 0.1.0 becomes 0.2.0 (new features, backward-compatible)
--bump major — 0.1.0 becomes 1.0.0 (breaking changes)

If no version is found in SKILL.md, the CLI defaults to 0.1.0 as the starting version before applying the bump.