Reskill 使用指南

声明式 skill 管理，像 npm/Go modules 一样安装、版本控制、同步和分享 AI agent skills

快速开始

⚠️ 系统要求：Node.js >= 18.0.0

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

特性

一键安装
用一条命令从任何 Git 仓库安装 skill
声明式配置
skills.json + skills.lock 确保团队一致性
灵活版本控制
支持精确版本、semver 范围、分支、commit
多注册源支持
GitHub、GitLab、自托管、私有仓库
多 Agent 支持
Cursor、Claude Code、Codex、Windsurf、GitHub Copilot 等
Registry 支持
发布和分享 skill 到 Registry

命令

基础命令

命令	别名	描述
`init`	-	初始化 skills.json
`install [skills...]`	`i`	安装一个或多个 skill
`list`	`ls`	列出已安装的 skill
`info <skill>`	-	显示 skill 详情
`update [skill]`	`up`	更新 skill
`outdated`	-	检查过期的 skill
`uninstall <skill>`	un`, `rm`, `remove	移除 skill
`publish [path]`	`pub`	发布 skill 到 Registry
`login`	-	登录 Registry
`logout`	-	退出登录
`whoami`	-	显示当前登录用户
`doctor`	-	诊断环境并检查问题
`completion install`	-	安装 Shell 自动补全

常用选项

选项	适用命令	描述
`--no-save`	install	安装但不保存到 skills.json（个人 skill）
`-g, --global`	install, uninstall, list	全局安装/管理 skill（用户目录）
`-a, --agent <agents...>`	install	指定目标代理（如 cursor, claude-code）
`--mode <mode>`	install	安装模式：symlink（默认）或 copy
`--all`	install	安装到所有代理
`-y, --yes`	install, uninstall, publish	跳过确认提示
`-f, --force`	install	强制重新安装
`-j, --json`	list, info, outdated, doctor	以 JSON 格式输出

💡 运行 reskill <command> --help 查看完整选项和详细用法

来源格式

# GitHub 简写
npx reskill@latest install github:user/skill@v1.0.0

# GitLab 简写
npx reskill@latest install gitlab:group/skill@latest

# 完整 Git URL (HTTPS)
npx reskill@latest install https://github.com/user/skill.git

# 完整 Git URL (SSH)
npx reskill@latest install git@github.com:user/skill.git

# GitHub/GitLab 网页 URL（包含分支和子路径）
npx reskill@latest install https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines

# 自定义注册源（自托管 GitLab 等）
npx reskill@latest install gitlab.example.com:team/skill@v1.0.0

# HTTP/OSS 压缩包
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

# 一次安装多个 skill
npx reskill@latest install github:user/skill1 github:user/skill2@v1.0.0

Monorepo 支持

对于包含多个 skill 的仓库（monorepo），可以指定 skill 目录的路径：

# 简写格式带子路径
npx reskill@latest install github:org/monorepo/skills/planning@v1.0.0
npx reskill@latest install gitlab:company/skills/frontend/components@latest

# URL 格式带子路径
npx reskill@latest install https://github.com/org/monorepo.git/skills/planning@v1.0.0
npx reskill@latest install git@gitlab.example.com:team/skills.git/backend/apis@v2.0.0

# GitHub 网页 URL 自动提取子路径
npx reskill@latest install https://github.com/org/monorepo/tree/main/skills/planning

⚠️ 要求：指定的目录必须包含有效的 SKILL.md 文件，遵循 Agent Skills 规范

HTTP/OSS URL 支持

可以从 HTTP/HTTPS URL 直接安装指向压缩包的 skill：

格式	示例	说明
HTTPS URL	`https://example.com/skill.tar.gz`	直接下载链接
阿里云 OSS	`https://bucket.oss-cn-hangzhou.aliyuncs.com/skill.tar.gz`	阿里云 OSS URL
AWS S3	`https://bucket.s3.amazonaws.com/skill.tar.gz`	AWS S3 URL
OSS 协议	`oss://bucket/path/skill.tar.gz`	阿里云 OSS 简写
S3 协议	`s3://bucket/path/skill.tar.gz`	AWS S3 简写

📦 支持的压缩格式：.tar.gz、.tgz、.zip、.tar

版本规范

格式	示例	描述
精确版本	`@v1.0.0`	锁定到特定标签
最新版本	`@latest`	获取最新标签
范围	`@^2.0.0`	Semver 兼容 (>=2.0.0 <3.0.0)
分支	`@branch:develop`	指定分支
Commit	`@commit:abc1234`	指定 commit hash
(无)	-	默认分支 (main)

配置

skills.json

{
  "skills": {
    "planning": "github:user/planning-skill@v1.0.0",
    "my-tool": "gitlab:team/tool@latest"
  },
  "registries": {
    "gitlab": "https://gitlab.example.com"
  },
  "defaults": {
    "installDir": ".skills",
    "targetAgents": ["cursor", "claude-code"],
    "installMode": "symlink"
  }
}

私有仓库

reskill 使用你现有的 git 凭据（SSH 密钥或凭据助手）。对于 CI/CD：

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

多 Agent 支持

skill 默认安装到 .skills/ 目录，可以与任何 Agent 集成：

代理	路径
Cursor	.cursor/rules/` 或 `.cursor/skills/
Claude Code	`.claude/skills/`
Codex	`.codex/skills/`
Windsurf	`.windsurf/skills/`
GitHub Copilot	`.github/skills/`

指定 Agent 安装

# 安装到特定代理
npx reskill@latest install github:user/skill -a cursor
npx reskill@latest install github:user/skill -a claude-code cursor

# 安装到多个代理
npx reskill@latest install github:user/skill --agent cursor --agent claude-code

发布 skill

将你的 skill 发布到 Registry 供他人使用：

# 登录 Registry
reskill login

# 验证但不发布（预览模式）
reskill publish --dry-run

# 发布 skill
reskill publish

环境变量

变量	描述	默认值
`RESKILL_CACHE_DIR`	全局缓存目录	~/.reskill-cache
`RESKILL_TOKEN`	认证 Token（优先于 ~/.reskillrc）	-
`RESKILL_REGISTRY`	默认 Registry URL	https://registry.reskill.dev
`DEBUG`	启用调试日志	-
`NO_COLOR`	禁用彩色输出	-

SKILL.md 文件格式

每个 skill 目录必须包含一个 SKILL.md 文件，定义 skill 的元信息和内容。

基本结构

---
name: planning-with-files
description: |
  帮助 AI 编码助手进行任务规划和文件管理。
version: 1.0.0
license: MIT
compatibility: cursor claude-code
allowed_tools: read_file write_file run_terminal_cmd
---

# Planning with Files

这个 skill 帮助 AI 编码助手进行任务规划...

## 使用方法

1. 描述你的任务目标
2. AI 将自动创建计划文件

Frontmatter 字段

字段	必填	说明
`name`	否	skill 名称（默认使用目录名）
`description`	是	skill 描述
`version`	否	语义化版本号
`license`	否	许可证类型
`compatibility`	否	兼容的 AI 工具，空格分隔
`allowed_tools`	否	允许 AI 使用的工具，空格分隔

📖 更多详情请参考 Agent Skills 规范

常见问题

Q: 如何初始化项目？

在项目根目录运行：

npx reskill@latest init

Q: 如何安装 skill 到特定 Agent？

使用 -a 或 --agent 选项：

npx reskill@latest install github:user/skill -a cursor
npx reskill@latest install github:user/skill --agent claude-code

Q: 如何安装私有仓库的 skill？

确保已配置 SSH 密钥或 Git 凭据，然后正常安装：

# SSH
npx reskill@latest install git@github.com:org/private-skill.git

# HTTPS（会提示输入凭据）
npx reskill@latest install https://github.com/org/private-skill.git

Q: 如何更新所有 skill？

运行 update 命令：

# 更新所有 skill
npx reskill@latest update

# 更新特定 skill
npx reskill@latest update planning

Q: 如何查看已安装的 skill？

npx reskill@latest list

# 查看全局安装的 skill
npx reskill@latest list -g

Q: 如何诊断问题？

运行 doctor 命令检查环境：

npx reskill@latest doctor