# Reskill Usage

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

- Skill: `kanyun-inc/reskill-usage` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kanyun-inc/reskill-usage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kanyun-inc/reskill-usage/raw
- Safety review: pending (external: skill-scanner PASS, skillspector FAIL)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: kanyun-inc (https://skillmd.com/u/kanyun-inc)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/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`:

```bash
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.

```bash
# 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

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

```bash
# 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 git@github.com: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, you can install a specific skill by path or install all skills from a parent directory:

```bash
# 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 git@gitlab.company.com: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

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

```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

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

```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

# 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

```bash
# 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

```bash
# 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

```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

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

```bash
# 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

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

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