Awesome-omni-skill 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.

install

source · Clone the upstream repo

git clone https://github.com/diegosouzapw/awesome-omni-skill

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/tools/reskill-usage" ~/.claude/skills/diegosouzapw-awesome-omni-skill-reskill-usage && rm -rf "$T"

manifest: skills/tools/reskill-usage/SKILL.md

source content

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

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:

```
--registry
```
CLI option
```
RESKILL_REGISTRY
```
environment variable
```
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/"