Getting Started

Install the SkillReg CLI and push your first AI agent skill to the registry in under 5 minutes. Step-by-step quickstart guide for all platforms.

Prerequisites

Before installing the SkillReg CLI, make sure you have the following:

  • Node.js 18 or later — check with node --version
  • A package manager: npm, pnpm, or yarn
  • A SkillReg account — sign up at skillreg.dev if you haven't already

Installation

Install the CLI globally using your preferred package manager:

Terminal
npm install -g @skillreg/cli

Or with pnpm / yarn:

Terminal
pnpm add -g @skillreg/cli
# or
yarn global add @skillreg/cli

Verify the installation by running:

Terminal
skillreg --version

Quick Start

Get up and running in 5 steps. By the end of this walkthrough, you will have created, published, and installed your first skill.

Step 1 — Set up the CLI

Run the interactive setup wizard. It will walk you through authentication, choosing your default organization, AI agent, and install scope.

Terminal
skillreg setup
skillreg setup
Welcome to SkillReg! Let's set up your CLI.

Step 1/4 — Authentication

  How do you want to log in?
  ❯ Browser login (recommended)
    Paste a token manually

  ✓ Logged in successfully!

Step 2/4 — Default organization

  ✓ Default org set to: my-company

Step 3/4 — Default agent

  Which AI agent do you use?
  ❯ Claude (recommended)
    Codex
    Cursor

  ✓ Default agent set to: claude

Step 4/4 — Install scope

  Where should skills be installed by default?
  ❯ Project (recommended)
    User (global)

  ✓ Default scope set to: project

  ─────────────────────────────────
  ✓ Setup complete! Your config:

    Org:    my-company
    Agent:  claude
    Scope:  project

One-time setup

You only need to run skillreg setup once per machine. After that, the CLI remembers your preferences in ~/.skillreg/config.json.

Step 2 — Initialize a new skill

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

Terminal
skillreg init my-skill
Output
✓ Created skill: my-skill/
  └── SKILL.md

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

Step 3 — Edit the SKILL.md

Open my-skill/SKILL.md in your editor. The generated file includes YAML frontmatter (name, version, metadata) and placeholder sections for instructions and examples. Replace the placeholders with your actual skill content:

my-skill/SKILL.md
---
name: "my-skill"
description: "Generates unit tests for TypeScript projects"
metadata:
  author: "your-name"
  version: "0.1.0"
  tags:
    - "testing"
    - "typescript"
---

# my-skill

## Instructions

When the user asks you to write tests, follow these rules:
- Use vitest as the test runner
- Colocate test files next to source files
- Prefer `describe` / `it` blocks over `test`

## Examples

Given a file `utils.ts`, generate `utils.test.ts` with
full coverage of exported functions.

Frontmatter matters

The name and version fields in the frontmatter are used by the registry to identify and version your skill. See the SKILL.md Format page for the full specification.

Step 4 — Push to the registry

Publish your skill so others in your organization can use it:

Terminal
skillreg push ./my-skill
Output
Packaging my-skill@0.1.0...
  ✓ Pushed my-skill@0.1.0
    SHA256: a3f2b1c...

The CLI packages the directory into a tarball, computes a SHA-256 checksum, and uploads it to the registry. If your organization has approval workflows enabled, the version will be marked as pending until an admin approves it.

Step 5 — Pull on another machine

Install the skill on another machine (or for a teammate) with a single command:

Terminal
skillreg pull @my-company/my-skill
Output
Pulling my-skill@latest from @my-company...
  ✓ Installed to .claude/skills/my-skill

The skill is extracted into the appropriate agent directory based on your configuration. By default, it installs to .claude/skills/my-skill in the current project.

Version pinning

You can pull a specific version with skillreg pull @my-company/my-skill@1.2.0 or use semver ranges like @^1.0.0.

What's Next

Now that you have the basics down, explore these pages to go further:

  • Authentication — Browser login, token-based login for CI/CD, and identity management.
  • Publishing Skills — Version bumping, dry runs, tags, and approval workflows.
  • SKILL.md Format — Full specification of the frontmatter fields, environment variables, and content structure.
  • Installing Skills — Multi-agent installs, scopes, and semver resolution.