reskill-usage

name	reskill-usage
description	Teaches AI agents how to use reskill — a Git-based package manager for AI agent skills. Covers CLI commands, install formats, configuration, publishing, and common workflows.
version	0.1.0
author	reskill
tags	["cli","package-manager","skills","reskill"]

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:

npm install -g reskill        # Global install
npx 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

# Initialize a new project
npx reskill@latest init

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

# List installed skills
npx reskill@latest list

Commands

Command	Alias	Description
init	-	Initialize skills.json
find <query>	-	Search for skills in the registry
install [skills...]	i	Install one or more skills
list	ls	List installed skills
info <skill>	-	Show skill details
update [skill]	up	Update skills
outdated	-	Check for outdated skills
uninstall <skill>	un, rm, remove	Remove a skill
publish [path]	pub	Publish 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 issues
completion install	-	Install shell tab completion

¹ 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

Option	Commands	Description
--no-save	install	Install without saving to skills.json (for personal skills)
-g, --global	install, uninstall, list	Install/manage skills globally (user directory)
-a, --agent <agents...>	install	Specify target agents (e.g., cursor, claude-code)
--mode <mode>	install	Installation mode: symlink (default) or copy
--all	install	Install to all agents
-y, --yes	install, uninstall, publish	Skip confirmation prompts
-f, --force	install	Force reinstall even if already installed
-s, --skill <names...>	install	Select specific skill(s) by name from a multi-skill repo
--list	install	List available skills in the repository without installing
-r, --registry <url>	install	Registry URL override for registry-based installs
-j, --json	list, info, outdated, doctor	Output as JSON

Source Formats

reskill supports installing skills from multiple sources:

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

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

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

# Full Git URL (SSH)
npx reskill@latest install [e-mail]:user/skill.git

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

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

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

# Registry-based (requires registry deployment)
npx reskill@latest install @scope/skill-name@1.0.0
npx reskill@latest install skill-name

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

Monorepo Support

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

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

# URL format with subpath
npx reskill@latest install https://github.com/org/monorepo.git/skills/planning@v1.0.0
npx reskill@latest install [e-mail]:team/skills.git/backend/apis@v2.0.0

# GitHub web URL automatically extracts subpath
npx reskill@latest 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:

Format	Example	Description
HTTPS URL	https://example.com/skill.tar.gz	Direct download URL
Aliyun OSS	https://bucket.oss-cn-hangzhou.aliyuncs.com/skill.tar.gz	Aliyun OSS URL
AWS S3	https://bucket.s3.amazonaws.com/skill.tar.gz	AWS S3 URL
OSS Protocol	oss://bucket/path/skill.tar.gz	Shorthand for Aliyun OSS
S3 Protocol	s3://bucket/path/skill.tar.gz	Shorthand for AWS S3

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

Version Formats

Format	Example	Description
Exact	@v1.0.0	Lock to specific tag
Latest	@latest	Get the latest tag
Range	@^2.0.0	Semver compatible (>=2.0.0 <3.0.0)
Branch	@branch:develop	Specific branch
Commit	@commit:abc1234	Specific commit hash
(none)	-	Default branch (main)

Configuration

skills.json

The project configuration file, created by reskill init:

{
  "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

Variable	Description	Default
RESKILL_CACHE_DIR	Global cache directory	~/.reskill-cache
RESKILL_TOKEN	Auth token (takes precedence over ~/.reskillrc)	-
RESKILL_REGISTRY	Default registry URL	https://registry.reskill.dev
DEBUG	Enable debug logging	-
NO_COLOR	Disable colored output	-

Multi-Agent Support

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

Agent	Path
Cursor	.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:

# 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

Note: Publishing requires a private registry deployment.

Authentication

# Login with a token (obtain from the registry web UI)
reskill login --registry <url> --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).

Registry URL resolution priority:

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

Publishing a Skill

# Validate without publishing (recommended first step)
reskill publish --dry-run

# Publish the skill
reskill publish

# Publish from a specific directory
reskill publish ./path/to/skill

# Skip confirmation
reskill 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

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

# 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

# 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

Scope	Flag	Directory	Use Case
Project	-	.skills/ (in project)	Team-shared skills, committed to git
Global	-g	~/.agents/skills/	Personal skills, available in all projects

# 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

# 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 Message	Cause	Solution
skills.json not found	Project not initialized	Run reskill init
Unknown scope @xyz	No registry configured for this scope	Check registries in skills.json or use full Git URL
Skill not found	Skill name doesn't exist in registry	Verify skill name; check reskill find <query>
Version not found	Requested version doesn't exist	Run reskill info <skill> to see available versions
Permission denied	Auth issue when publishing	Run reskill login; check token scope
Token is invalid or expired	Stale authentication	Re-authenticate with reskill login --token <new-token>
Network error	Cannot reach Git host or registry	Check network; run reskill doctor for diagnostics
Conflict: directory already exists	Skill already installed	Use --force to reinstall

Private Repositories

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

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