kanyun-inc/reskill-usage

<!-- source: README.md --> <!-- synced: 2026-05-11 -->

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.)

AI Agent Execution Rules

AI agents cannot respond to interactive prompts mid-command. Always add -y to commands that support confirmation prompts (install, uninstall, publish) to prevent the command from hanging.

# Correct — will not hang
reskill install github:user/skill -y
reskill uninstall skill-name -y
reskill publish -y

# Wrong — will hang waiting for confirmation
reskill install github:user/skill
reskill uninstall skill-name

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 | 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 | | group | - | Manage skill groups ¹ | | 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 [action] | - | Setup or remove shell tab completion |

¹ Registry commands (group, 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) | | -a, --agent <agent> | list | List skills installed to a specific agent | | --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 | | --skip-manifest | install | Skip all skills.json and skills.lock writes (for platform integration) | | -t, --token <token> | install, find, group, publish, login | Auth token for registry API requests (for CI/CD) | | -r, --registry <url> | install, find, group, publish, login, logout, whoami | Registry URL override for registry-enabled commands | | --tag <tag> | publish | Git tag to publish | | --access <level> | publish | Access level: public (default) or restricted | | -n, --dry-run | publish | Validate without publishing | | -g, --group <path> | publish | Publish skill into a group (e.g., kanyun/frontend) | | -j, --json | list, info, outdated, doctor, group, find | Output as JSON | | -l, --limit <n> | find | Maximum number of search results | | --skip-network | doctor | Skip network connectivity checks |

Source Formats

reskill supports installing skills from multiple sources:

# GitHub shorthand
npx reskill@latest install github:user/[email protected]

# 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 [email protected]: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/[email protected]

# 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/[email protected]
npx reskill@latest install skill-name

# Install multiple skills at once
npx reskill@latest install github:user/skill1 github:user/[email protected]

Monorepo Support

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

# Shorthand format with subpath
npx reskill@latest install github:org/monorepo/skills/[email protected]
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/[email protected]
npx reskill@latest install [email protected]:team/skills.git/backend/[email protected]

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

# Point to a parent directory — auto-detects and installs all child skills
npx 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:

| 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/[email protected]",
    "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 | | RESKILL_NO_MANIFEST | Skip skills.json and skills.lock writes (set to 1 to enable) | - | | DEBUG | Enable debug logging | - | | VERBOSE | Enable debug logging (same effect as DEBUG) | - | | NO_COLOR | Disable colored output | - |

Multi-Agent Support

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

| Agent | Path | | -------------- | ------------------ | | Amp | .agents/skills | | Antigravity | .agent/skills | | Claude Code | .claude/skills | | Claude Cowork 3P | App-managed global directory | | Clawdbot | skills | | Codex | .codex/skills | | Cursor | .cursor/skills | | Droid | .factory/skills | | Gemini CLI | .gemini/skills | | GitHub Copilot | .github/skills | | Goose | .goose/skills | | Kilo Code | .kilocode/skills | | Kiro CLI | .kiro/skills | | Neovate | .neovate/skills | | OpenCode | .opencode/skills | | Roo Code | .roo/skills | | Trae | .trae/skills | | Windsurf | .windsurf/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

# List skills installed to a specific agent
reskill list -a cursor
reskill list -a claude-cowork-3p

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 with name, version, and description in its frontmatter.

Common Workflows

First-Time Project Setup

# 1. Initialize the project
reskill init -y

# 2. Install skills your project needs
reskill install github:user/[email protected] 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 | | Claude Cowork 3P | -a claude-cowork-3p | App-managed global directory | Always global, no skills.json writes |

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

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

# Install to Claude Cowork 3P (always global)
reskill install github:user/skill -a claude-cowork-3p

# 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/"