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

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

### Monorepo Support

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

**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`             | 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` — 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://rush.zhenguanyu.com`  |
| `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:

## Publishing

### Authentication

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

### Publishing a Skill

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

### Team Collaboration

When a teammate clones the project, they run:

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

### Checking and Updating Skills