publish

rolecraft publish

Publish a skill to the rolecraft Registry.

Usage

rolecraft publish <source> [--repo <owner/repo>] [--dry-run] [--yes]
                     [--slug <slug>] [--name <name>]

Description

Publishes a SKILL.md to the centralised rolecraft Registry. The registry acts as a community-driven index of skills, similar to npm for Node.js packages or PyPI for Python.

Option A: CLI publish (recommended)

When you publish via CLI:

1. Reads the SKILL.md metadata from your local skill directory.
2. Detects the GitHub repository from your local git remote (or --repo flag).
3. Forks the rolecraft-sh/registry repository (one-time setup, automatic).
4. Updates index.json with a new entry.
5. Opens a pull request via GitHub API.
6. A maintainer is notified to merge once CI validation passes.

Option B: Manual PR (without CLI)

Don't use rolecraft CLI? You can add your skill by editing index.json directly on GitHub:

1. Go to https://github.com/rolecraft-sh/registry
2. Click Fork
3. Edit index.json — add your skill entry to the skills array
4. Commit to a new branch
5. Open a Pull Request

Entry format:

{
  "slug": "my-skill",
  "name": "My Skill",
  "description": "What this skill does",
  "repo": "your-username/your-skill-repo",
  "author": "your-username",
  "versions": ["v1.0.0"],
  "latest": "v1.0.0"
}

Constraints

Rule	Details
Slug format	kebab-case: ^[a-z0-9]+(-[a-z0-9]+)*$, e.g. react-rules
Unique slug	Every slug must be unique across all skills
Author match	The author field must be your GitHub username (checked by CI)
Repo must exist	The repo must be a valid GitHub repo that contains a SKILL.md
Schema validation	Entry must match schema.json in the registry repo

Validation checks (auto)

Each PR triggers:

1. JSON syntax check
2. Schema validation against schema.json
3. Duplicate slug check
4. Owner verification — PR author must match the author field