reskill Usage Guide

reskill is a Git-based package manager for AI agent skills. It provides declarative configuration (skills.json + skills.lock), flexible versioning, and multi-agent support for installing, managing, and sharing skills across projects and teams.

Requirements: Node.js >= 18.0.0

CLI usage: If reskill is installed globally, use it directly. Otherwise use npx reskill@latest:

bash
1npm install -g reskill        # Global install
2npx reskill@latest <command>  # Or use npx directly (no install needed)

When to Use This Skill

Use this skill when the user:

• Wants to install, update, or manage AI agent skills
• Mentions skills.json, skills.lock, or reskill-related concepts
• Wants to publish a skill to a registry
• Asks about supported install formats (GitHub, GitLab, HTTP, OSS, registry, etc.)
• Encounters reskill-related errors or needs troubleshooting
• Wants to set up a project for skill management
• Asks about multi-agent skill installation (Cursor, Claude Code, Codex, etc.)

Quick Start

bash
1# Initialize a new project
2npx reskill@latest init
3
4# Install a skill
5npx reskill@latest install github:anthropics/skills/skills/frontend-design@latest
6
7# List installed skills
8npx reskill@latest list

Commands

¹ Registry commands (publish, login, logout, whoami) require a private registry deployment. Not available for public use yet.

Run reskill <command> --help for complete options and detailed usage.

Common Options

Source Formats

reskill supports installing skills from multiple sources:

bash
1# GitHub shorthand
2npx reskill@latest install github:user/skill@v1.0.0
3
4# GitLab shorthand
5npx reskill@latest install gitlab:group/skill@latest
6
7# Full Git URL (HTTPS)
8npx reskill@latest install https://github.com/user/skill.git
9
10# Full Git URL (SSH)
11npx reskill@latest install git@github.com:user/skill.git
12
13# GitHub/GitLab web URL (with branch and subpath)
14npx reskill@latest install https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
15
16# Custom registry (self-hosted GitLab, etc.)
17npx reskill@latest install gitlab.company.com:team/skill@v1.0.0
18
19# HTTP/OSS archives
20npx reskill@latest install https://example.com/skills/my-skill-v1.0.0.tar.gz
21npx reskill@latest install oss://bucket/path/skill.tar.gz
22npx reskill@latest install s3://bucket/path/skill.zip
23
24# Registry-based (requires registry deployment)
25npx reskill@latest install @scope/skill-name@1.0.0
26npx reskill@latest install skill-name
27
28# Install multiple skills at once
29npx reskill@latest install github:user/skill1 github:user/skill2@v1.0.0

Monorepo Support

For repositories containing multiple skills, you can install a specific skill by path or install all skills from a parent directory:

bash
1# Shorthand format with subpath
2npx reskill@latest install github:org/monorepo/skills/planning@v1.0.0
3npx reskill@latest install gitlab:company/skills/frontend/components@latest
4
5# URL format with subpath
6npx reskill@latest install https://github.com/org/monorepo.git/skills/planning@v1.0.0
7npx reskill@latest install git@gitlab.company.com:team/skills.git/backend/apis@v2.0.0
8
9# GitHub web URL automatically extracts subpath
10npx reskill@latest install https://github.com/org/monorepo/tree/main/skills/planning
11
12# Point to a parent directory — auto-detects and installs all child skills
13npx reskill@latest install https://github.com/org/monorepo/tree/main/skills

When the target directory has no root SKILL.md but contains subdirectories with SKILL.md files, reskill automatically discovers and installs all child skills. Each skill is saved separately in skills.json.

HTTP/OSS URL Support

Skills can be installed directly from HTTP/HTTPS URLs pointing to archive files:

Supported archive formats: .tar.gz, .tgz, .zip, .tar

Version Formats

Configuration

skills.json

The project configuration file, created by reskill init:

json
1{
2  "skills": {
3    "planning": "github:user/planning-skill@v1.0.0",
4    "internal-tool": "internal:team/tool@latest"
5  },
6  "registries": {
7    "internal": "https://gitlab.company.com"
8  },
9  "defaults": {
10    "installDir": ".skills",
11    "targetAgents": ["cursor", "claude-code"],
12    "installMode": "symlink"
13  }
14}

• skills — Installed skill references (name → source ref)
• registries — Custom Git registry aliases
• defaults.installDir — Where skills are stored (default: .skills)
• defaults.targetAgents — Default agents to install to
• defaults.installMode — symlink (default, recommended) or copy

Environment Variables

Multi-Agent Support

Skills are installed to .skills/ by default and can be integrated with any agent:

Use --agent to target specific agents, or --all to install to all detected agents:

bash
1# Install to specific agents
2reskill install github:user/skill -a cursor claude-code
3
4# Install to all detected agents
5reskill install github:user/skill --all

Publishing

Note: Publishing requires a private registry deployment.

Authentication

bash
1# Login with a token (obtain from the registry web UI)
2reskill login --registry <url> --token <token>
3
4# Check current login status
5reskill whoami
6
7# Logout
8reskill logout

Tokens are stored in ~/.reskillrc. You can also use the RESKILL_TOKEN environment variable (takes precedence, useful for CI/CD).

Registry URL resolution priority:

1. --registry CLI option
2. RESKILL_REGISTRY environment variable
3. defaults.publishRegistry in skills.json

Publishing a Skill

bash
1# Validate without publishing (recommended first step)
2reskill publish --dry-run
3
4# Publish the skill
5reskill publish
6
7# Publish from a specific directory
8reskill publish ./path/to/skill
9
10# Skip confirmation
11reskill publish -y

The skill directory must contain a valid SKILL.md. A skill.json with name, version, and description is also required for publishing.

Common Workflows

First-Time Project Setup

bash
1# 1. Initialize the project
2reskill init -y
3
4# 2. Install skills your project needs
5reskill install github:user/skill1@v1.0.0 github:user/skill2@latest -y
6
7# 3. Verify installation
8reskill list
9
10# 4. Commit skills.json and skills.lock to version control
11# (These files ensure team members get the same skill versions)

Team Collaboration

When a teammate clones the project, they run:

bash
1# Reinstall all skills from skills.json (like npm install)
2reskill install

This reads skills.json + skills.lock and installs the exact same versions.

Checking and Updating Skills

bash
1# Check which skills have newer versions
2reskill outdated
3
4# Update all skills
5reskill update
6
7# Update a specific skill
8reskill update skill-name

Global vs Project-Level Installation

bash
1# Project-level (default)
2reskill install github:user/skill
3
4# Global (personal, all projects)
5reskill install github:user/skill -g
6
7# Personal project-level (not saved to skills.json)
8reskill install github:user/skill --no-save

Diagnosing Issues

bash
1# Run environment diagnostics
2reskill doctor
3
4# JSON output for programmatic use
5reskill doctor --json

The doctor command checks: reskill version, Node.js version, Git availability, cache directory, skills.json validity, skills.lock sync, installed skills integrity, and network connectivity.

Troubleshooting

Private Repositories

reskill uses your existing git credentials (SSH keys or credential helper). For CI/CD environments:

bash
1# GitLab CI
2git config --global url."https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.company.com/".insteadOf "https://gitlab.company.com/"