Git-based Skills Package Manager for AI Agents

Declarative skill management like npm/Go modules — install, version, sync, and share AI agent skills

English | 简体中文

Quick Start

npx reskill@latest init
npx reskill@latest install github:anthropics/skills/skills/frontend-design@latest
npx reskill@latest list

Features

• One-click install — Install any skill from any Git repo with a single command
• Declarative config — skills.json + skills.lock for team consistency
• Flexible versioning — Exact versions, semver ranges, branches, commits
• Multi-source — GitHub, GitLab, self-hosted repos, HTTP/OSS archives
• Multi-agent — Cursor, Claude Code, Codex, Windsurf, GitHub Copilot, and more
• Registry support — Publish and share skills via registry

Installation

Requirements: Node.js >= 18.0.0

npm install -g reskill        # Global install
npx reskill@latest <command>  # Or use npx directly

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.

Common Options

| Option | Commands | Description | | ------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------- | | --no-save | install | Install without saving to skills.json (for personal skills) | | -g, --global | install, uninstall, list, outdated, update | 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) | | --base-dir <dir> | install, uninstall, list, outdated, update | Project root to resolve skills.json, skills.lock and agent skill directories against | | -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 |

Run reskill <command> --help for complete options and detailed usage.

Group Command Quick Reference

# List groups
reskill group list
reskill group list --tree

# Create / inspect / delete groups
reskill group create "Frontend Team" --description "Frontend skills"
reskill group info kanyun/frontend
reskill group delete kanyun/frontend --dry-run
reskill group delete kanyun/frontend -y

# Manage members
reskill group member list kanyun/frontend
reskill group member add kanyun/frontend alice bob --role developer
reskill group member remove kanyun/frontend alice
reskill group member role kanyun/frontend bob maintainer

publish --group <path> normalizes and validates the path before request.
For full group path rules, see CLI Specification - group.

Source Formats

# 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 (monorepo), 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 Specification

| 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

{
  "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"
  }
}

Private Repositories

reskill uses your existing git credentials (SSH keys or credential helper). For CI/CD:

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

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 (Beta) | App-managed Claude-3p/local-agent-mode-sessions/skills-plugin/<org>/<account>/skills | | 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 |

Custom Agent Targets

Not every tool is in the built-in table. Declare your own alias → directory under customAgents in skills.json, then use it anywhere a built-in agent name is accepted (-a, defaults.targetAgents, list -a, uninstall):

{
  "skills": {},
  "defaults": { "targetAgents": ["claude-code", "cc-switch"] },
  "customAgents": {
    "cc-switch": {
      "path": ".cc-switch/skills",
      "globalPath": "~/.cc-switch/skills"
    }
  }
}

• path — project-level directory, relative to the project root (required).
• globalPath — absolute directory (a leading ~ expands to your home) used for -g/--global installs. Global installs into a custom agent without a globalPath are rejected.

You can also declare a custom agent inline with alias:path on the CLI. On a successful project install the alias is written back into skills.json under customAgents, so subsequent commands (reskill install, list -a, …) reuse it without repeating the path:

reskill install github:user/skill -a cc-switch:.cc-switch/skills
# → skills.json now contains customAgents["cc-switch"] = { "path": ".cc-switch/skills" }

Isolated Project Roots

By default, project-level commands resolve everything against the current directory. --base-dir points them at a different project root instead — skills.json, skills.lock and every agent directory move together:

# Installs into ./agents/foo/.claude/skills and ./agents/foo/.cursor/skills,
# reading and writing ./agents/foo/skills.json
reskill install github:user/skill --base-dir agents/foo -a claude-code cursor

This is useful when several agent definitions live side by side on one machine and each needs its own skill set:

agents/
├── foo/
│   ├── skills.json          # foo's dependencies
│   ├── .claude/skills/      # foo's skills
│   └── .cursor/skills/
└── bar/
    ├── skills.json          # bar's dependencies, independent of foo
    └── .claude/skills/

Install into each root separately — one reskill call per root:

reskill install github:user/skill-a --base-dir agents/foo -a claude-code -y
reskill install github:user/skill-b --base-dir agents/bar -a claude-code -y

Run these sequentially. The global cache is not concurrency-safe: two reskill processes installing the same skill version at the same time can interfere with each other.

The same flag works for reading back and maintaining each root:

reskill list --base-dir agents/foo
reskill outdated --base-dir agents/foo
reskill update --base-dir agents/foo
reskill uninstall skill-a --base-dir agents/foo

To let a runtime pick these skills up, point its own config root at the matching directory — for Claude Code, CLAUDE_CONFIG_DIR=agents/foo/.claude.

Notes:

• The directory must already exist; reskill will not create it.
• --base-dir cannot be combined with -g/--global, which always resolves to the user home directory.

Publishing Skills

Note: Publishing requires a private registry deployment. This feature is not available for public use yet.

Publish your skills to the registry for others to use:

# Group management examples
reskill group list
reskill group list --tree
reskill group create "Frontend Team" --description "Frontend skills"
reskill group info kanyun/frontend
reskill group member add kanyun/frontend alice bob --role developer

# Interactive login (recommended for humans — guides you through token setup)
reskill login

# Non-interactive login (for CI/CD — pass token directly)
reskill login --token <your-token>

# Validate without publishing (dry run)
reskill publish --dry-run

# Validate publish with target group
reskill publish --dry-run --group kanyun/frontend

# Publish the skill
reskill publish

For detailed publishing guidelines, see the CLI Specification.

Installing Private Skills

After logging in with reskill login, the token stored in ~/.reskillrc is automatically used during reskill install to access private skills:

# Token is automatically read from ~/.reskillrc (requires --registry to match)
reskill install @scope/private-skill --registry https://your-registry.com

# Or use RESKILL_TOKEN env var (works without --registry)
RESKILL_TOKEN=<token> reskill install @scope/private-skill

# Or pass token directly (for CI/CD)
reskill install @scope/private-skill --registry https://your-registry.com --token <token>

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

reskill checks for newer versions in the background and shows an upgrade tip after command execution.

Development

# Install dependencies
pnpm install

# Development mode
pnpm dev

# Build
pnpm build

# Run tests
pnpm test

# Run integration tests
pnpm test:integration

# Type check
pnpm typecheck

Acknowledgements

reskill was inspired by and references the implementations of these excellent projects:

• add-skill by Vercel Labs
• skild by Peiiii
• openskills by Numman Ali

Related Links

• Agent Skills Specification

License

MIT