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.

Security & Trust#

This skill instructs the agent to run CLI commands via reskill, an open-source, Git-based package manager for AI agent skills.

Why a specific registry? reskill supports multiple registries. This skill defaults to the Rush community registry ( https://rush.zhenguanyu.com/) — the primary public registry for the reskill ecosystem, similar to how npm defaults to https://registry.npmjs.org. Users can override it at any time via --registry, the RESKILL_REGISTRY environment variable, or defaults.publishRegistry in skills.json.

CLI execution approach: To avoid downloading remote code on every invocation, we recommend installing reskill globally first:

bash

npm install -g reskill

If a global installation is not available, npx reskill@latest can be used as a fallback. The agent should check for a global install ( which reskill) before falling back to npx.

Requirements: Node.js >= 18.0.0

Registry resolution (highest to lowest priority):

1. --registry <url> CLI option
2. RESKILL_REGISTRY environment variable
3. defaults.publishRegistry in skills.json
4. Default: https://rush.zhenguanyu.com/

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

# Initialize a new project
reskill init

# Install a skill
reskill install github:anthropics/skills/skills/frontend-design@latest

# List installed skills
reskill list

Commands#

CommandAliasDescriptioninit-Initialize skills.json``find <query>-Search for skills in the registryinstall [skills...]``iInstall one or more skillslist``lsList installed skillsinfo <skill>-Show skill detailsupdate [skill]``upUpdate skillsoutdated-Check for outdated skillsuninstall <skill>``un, rm, removeRemove a skillpublish [path]``pubPublish a skill to the registry ¹login-Authenticate with the registry ¹logout-Remove stored authentication ¹whoami-Display current logged in user ¹doctor-Diagnose environment and check for issuescompletion install-Install shell tab completion

¹ Registry commands ( publish, login, logout, whoami) use the configured registry (default: https://rush.zhenguanyu.com).

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

Common Options#

OptionCommandsDescription--no-save``installInstall without saving to skills.json (for personal skills)-g, --global``install, uninstall, listInstall/manage skills globally (user directory)-a, --agent <agents...>``installSpecify target agents (e.g., cursor, claude-code)--mode <mode>``installInstallation mode: symlink (default) or copy``--all``installInstall to all agents-y, --yes``install, uninstall, publishSkip confirmation prompts-f, --force``installForce reinstall even if already installed-s, --skill <names...>``installSelect specific skill(s) by name from a multi-skill repo--list``installList available skills in the repository without installing-r, --registry <url>``installRegistry URL override for registry-based installs-j, --json``list, info, outdated, doctorOutput as JSON

Source Formats#

reskill supports installing skills from multiple sources:

bash

# GitHub shorthand
reskill install github:user/skill@v1.0.0

# GitLab shorthand
reskill install gitlab:group/skill@latest

# Full Git URL (HTTPS)
reskill install https://github.com/user/skill.git

# Full Git URL (SSH)
reskill install git@github.com:user/skill.git

# GitHub/GitLab web URL (with branch and subpath)
reskill install https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines

# Custom registry (self-hosted GitLab, etc.)
reskill install gitlab.company.com:team/skill@v1.0.0

# HTTP/OSS archives
reskill install https://example.com/skills/my-skill-v1.0.0.tar.gz
reskill install oss://bucket/path/skill.tar.gz
reskill install s3://bucket/path/skill.zip

# Registry-based
reskill install @scope/skill-name@1.0.0 --registry https://rush.zhenguanyu.com
reskill install skill-name --registry https://rush.zhenguanyu.com

# Install multiple skills at once
reskill install github:user/skill1 github:user/skill2@v1.0.0

Monorepo Support#

For repositories containing multiple skills, specify the path to the skill directory:

bash

# Shorthand format with subpath
reskill install github:org/monorepo/skills/planning@v1.0.0
reskill install gitlab:company/skills/frontend/components@latest

# URL format with subpath
reskill install https://github.com/org/monorepo.git/skills/planning@v1.0.0
reskill install git@gitlab.company.com:team/skills.git/backend/apis@v2.0.0

# GitHub web URL automatically extracts subpath
reskill install https://github.com/org/monorepo/tree/main/skills/planning

Requirements: The specified directory must contain a valid SKILL.md file following the Agent Skills Specification.

HTTP/OSS URL Support#

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

FormatExampleDescriptionHTTPS URLhttps://example.com/skill.tar.gzDirect download URLAliyun OSShttps://bucket.oss-cn-hangzhou.aliyuncs.com/skill.tar.gzAliyun OSS URLAWS S3https://bucket.s3.amazonaws.com/skill.tar.gzAWS S3 URLOSS Protocoloss://bucket/path/skill.tar.gzShorthand for Aliyun OSSS3 Protocols3://bucket/path/skill.tar.gzShorthand for AWS S3

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

Version Formats#

FormatExampleDescriptionExact@v1.0.0Lock to specific tagLatest@latestGet the latest tagRange@^2.0.0Semver compatible (>=2.0.0 <3.0.0)Branch@branch:developSpecific branchCommit@commit:abc1234Specific commit hash(none)-Default branch (main)

Configuration#

skills.json#

The project configuration file, created by reskill init:

json

{
  "skills": {
    "planning": "github:user/planning-skill@v1.0.0",
    "internal-tool": "internal:team/tool@latest"
  },
  "registries": {
    "internal": "https://gitlab.company.com"
  },
  "defaults": {
    "installDir": ".skills",
    "targetAgents": ["cursor", "claude-code"],
    "installMode": "symlink"
  }
}

• 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#

VariableDescriptionDefaultRESKILL_CACHE_DIRGlobal cache directory~/.reskill-cache``RESKILL_TOKENAuth token (takes precedence over ~/.reskillrc)-RESKILL_REGISTRYDefault registry URLhttps://rush.zhenguanyu.com``DEBUGEnable debug logging-NO_COLORDisable colored output-

Multi-Agent Support#

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

AgentPathCursor.cursor/rules/ or .cursor/skills/Claude Code.claude/skills/Codex.codex/skills/Windsurf.windsurf/skills/GitHub Copilot.github/skills/OpenCode.opencode/skills/

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

bash

# Install to specific agents
reskill install github:user/skill -a cursor claude-code

# Install to all detected agents
reskill install github:user/skill --all

Publishing#

Authentication#

bash

# Login with a token (obtain from the registry web UI)
reskill login --registry https://rush.zhenguanyu.com --token <token>

# Check current login status
reskill whoami

# Logout
reskill logout

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

Publishing a Skill#

bash

# Validate without publishing (recommended first step)
reskill publish --dry-run --registry https://rush.zhenguanyu.com

# Publish the skill
reskill publish --registry https://rush.zhenguanyu.com

# Publish from a specific directory
reskill publish ./path/to/skill --registry https://rush.zhenguanyu.com

# Skip confirmation
reskill publish -y --registry https://rush.zhenguanyu.com

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. Initialize the project
reskill init -y

# 2. Install skills your project needs
reskill install github:user/skill1@v1.0.0 github:user/skill2@latest -y

# 3. Verify installation
reskill list

# 4. Commit skills.json and skills.lock to version control
# (These files ensure team members get the same skill versions)

Team Collaboration#

When a teammate clones the project, they run:

bash

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

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

Checking and Updating Skills#

bash

# Check which skills have newer versions
reskill outdated

# Update all skills
reskill update

# Update a specific skill
reskill update skill-name

Global vs Project-Level Installation#

ScopeFlagDirectoryUse CaseProject-.skills/ (in project)Team-shared skills, committed to gitGlobal-g``~/.agents/skills/Personal skills, available in all projectsbash

# Project-level (default)
reskill install github:user/skill

# Global (personal, all projects)
reskill install github:user/skill -g

# Personal project-level (not saved to skills.json)
reskill install github:user/skill --no-save

Diagnosing Issues#

bash

# Run environment diagnostics
reskill doctor

# JSON output for programmatic use
reskill 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#

Error MessageCauseSolutionskills.json not foundProject not initializedRun reskill init``Unknown scope @xyzNo registry configured for this scopeCheck registries in skills.json or use full Git URLSkill not foundSkill name doesn't exist in registryVerify skill name; check reskill find <query>``Version not foundRequested version doesn't existRun reskill info <skill> to see available versionsPermission deniedAuth issue when publishingRun reskill login; check token scopeToken is invalid or expiredStale authenticationRe-authenticate with reskill login --token <new-token>``Network errorCannot reach Git host or registryCheck network; run reskill doctor for diagnosticsConflict: directory already existsSkill already installedUse --force to reinstall

Private Repositories#

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

bash

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