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

# 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](https://github.com/nicepkg/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

| 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`) use the configured registry (default: `https://rush.zhenguanyu.com`).

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:

```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](https://agentskills.io).

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