reskill 1.3.0 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +90 -31
  2. package/README.zh-CN.md +97 -25
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -28,11 +28,14 @@ npx reskill@latest list
28
28
  - **One-click install** — Install any skill from any Git repo with a single command
29
29
  - **Declarative config** — `skills.json` + `skills.lock` for team consistency
30
30
  - **Flexible versioning** — Exact versions, semver ranges, branches, commits
31
- - **Multi-registry** — GitHub, GitLab, self-hosted, private repos
31
+ - **Multi-source** — GitHub, GitLab, self-hosted repos, HTTP/OSS archives
32
32
  - **Multi-agent** — Cursor, Claude Code, Codex, Windsurf, GitHub Copilot, and more
33
+ - **Registry support** — Publish and share skills via registry
33
34
 
34
35
  ## Installation
35
36
 
37
+ **Requirements:** Node.js >= 18.0.0
38
+
36
39
  ```bash
37
40
  npm install -g reskill # Global install
38
41
  npx reskill@latest <command> # Or use npx directly
@@ -40,17 +43,23 @@ npx reskill@latest <command> # Or use npx directly
40
43
 
41
44
  ## Commands
42
45
 
43
- | Command | Description |
44
- | --------------------- | ----------------------------------------- |
45
- | `init` | Initialize `skills.json` |
46
- | `install [skills...]` | Install one or more skills |
47
- | `list` | List installed skills |
48
- | `info <skill>` | Show skill details |
49
- | `update [skill]` | Update skills |
50
- | `outdated` | Check for outdated skills |
51
- | `uninstall <skill>` | Remove a skill |
52
- | `doctor` | Diagnose environment and check for issues |
53
- | `completion install` | Install shell tab completion |
46
+ | Command | Alias | Description |
47
+ | ------- | ----- | ----------- |
48
+ | `init` | - | Initialize `skills.json` |
49
+ | `install [skills...]` | `i` | Install one or more skills |
50
+ | `list` | `ls` | List installed skills |
51
+ | `info <skill>` | - | Show skill details |
52
+ | `update [skill]` | `up` | Update skills |
53
+ | `outdated` | - | Check for outdated skills |
54
+ | `uninstall <skill>` | `un`, `rm`, `remove` | Remove a skill |
55
+ | `publish [path]` | `pub` | Publish a skill to the registry ¹ |
56
+ | `login` | - | Authenticate with the registry ¹ |
57
+ | `logout` | - | Remove stored authentication ¹ |
58
+ | `whoami` | - | Display current logged in user ¹ |
59
+ | `doctor` | - | Diagnose environment and check for issues |
60
+
61
+ > ¹ Registry commands (`publish`, `login`, `logout`, `whoami`) require a private registry deployment. Not available for public use yet.
62
+ | `completion install` | - | Install shell tab completion |
54
63
 
55
64
  ### Common Options
56
65
 
@@ -60,7 +69,10 @@ npx reskill@latest <command> # Or use npx directly
60
69
  | `-g, --global` | `install`, `uninstall`, `list` | Install/manage skills globally (user directory) |
61
70
  | `-a, --agent <agents...>` | `install` | Specify target agents (e.g., `cursor`, `claude-code`) |
62
71
  | `--mode <mode>` | `install` | Installation mode: `symlink` (default) or `copy` |
63
-
72
+ | `--all` | `install` | Install to all agents |
73
+ | `-y, --yes` | `install`, `uninstall`, `publish` | Skip confirmation prompts |
74
+ | `-f, --force` | `install` | Force reinstall even if already installed |
75
+ | `-j, --json` | `list`, `info`, `outdated`, `doctor` | Output as JSON |
64
76
 
65
77
  Run `reskill <command> --help` for complete options and detailed usage.
66
78
 
@@ -70,20 +82,25 @@ Run `reskill <command> --help` for complete options and detailed usage.
70
82
  # GitHub shorthand
71
83
  npx reskill@latest install github:user/skill@v1.0.0
72
84
 
73
- # Full Git URL
85
+ # GitLab shorthand
86
+ npx reskill@latest install gitlab:group/skill@latest
87
+
88
+ # Full Git URL (HTTPS)
74
89
  npx reskill@latest install https://github.com/user/skill.git
75
90
 
76
- # GitHub web URL (with branch and subpath)
77
- npx reskill@latest install https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
91
+ # Full Git URL (SSH)
92
+ npx reskill@latest install git@github.com:user/skill.git
78
93
 
79
- # GitLab
80
- npx reskill@latest install gitlab:group/skill@latest
94
+ # GitHub/GitLab web URL (with branch and subpath)
95
+ npx reskill@latest install https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
81
96
 
82
- # Private registry
97
+ # Custom registry (self-hosted GitLab, etc.)
83
98
  npx reskill@latest install gitlab.company.com:team/skill@v1.0.0
84
99
 
85
- # Default registry (from skills.json)
86
- npx reskill@latest install user/skill@v1.0.0
100
+ # HTTP/OSS archives
101
+ npx reskill@latest install https://example.com/skills/my-skill-v1.0.0.tar.gz
102
+ npx reskill@latest install oss://bucket/path/skill.tar.gz
103
+ npx reskill@latest install s3://bucket/path/skill.zip
87
104
 
88
105
  # Install multiple skills at once
89
106
  npx reskill@latest install github:user/skill1 github:user/skill2@v1.0.0
@@ -108,15 +125,30 @@ npx reskill@latest install https://github.com/org/monorepo/tree/main/skills/plan
108
125
 
109
126
  **Requirements**: The specified directory must contain a valid `SKILL.md` file following the [Agent Skills Specification](https://agentskills.io).
110
127
 
128
+ ### HTTP/OSS URL Support
129
+
130
+ Skills can be installed directly from HTTP/HTTPS URLs pointing to archive files:
131
+
132
+ | Format | Example | Description |
133
+ | ------ | ------- | ----------- |
134
+ | HTTPS URL | `https://example.com/skill.tar.gz` | Direct download URL |
135
+ | Aliyun OSS | `https://bucket.oss-cn-hangzhou.aliyuncs.com/skill.tar.gz` | Aliyun OSS URL |
136
+ | AWS S3 | `https://bucket.s3.amazonaws.com/skill.tar.gz` | AWS S3 URL |
137
+ | OSS Protocol | `oss://bucket/path/skill.tar.gz` | Shorthand for Aliyun OSS |
138
+ | S3 Protocol | `s3://bucket/path/skill.tar.gz` | Shorthand for AWS S3 |
139
+
140
+ **Supported archive formats:** `.tar.gz`, `.tgz`, `.zip`, `.tar`
141
+
111
142
  ## Version Specification
112
143
 
113
- | Format | Example | Description |
114
- | ------ | ----------------- | -------------------- |
115
- | Exact | `@v1.0.0` | Lock to specific tag |
116
- | Latest | `@latest` | Get the latest tag |
117
- | Range | `@^2.0.0` | Semver compatible |
118
- | Branch | `@branch:develop` | Specific branch |
144
+ | Format | Example | Description |
145
+ | ------ | ------- | ----------- |
146
+ | Exact | `@v1.0.0` | Lock to specific tag |
147
+ | Latest | `@latest` | Get the latest tag |
148
+ | Range | `@^2.0.0` | Semver compatible (>=2.0.0 <3.0.0) |
149
+ | Branch | `@branch:develop` | Specific branch |
119
150
  | Commit | `@commit:abc1234` | Specific commit hash |
151
+ | (none) | - | Default branch (main) |
120
152
 
121
153
  ## Configuration
122
154
 
@@ -132,7 +164,9 @@ npx reskill@latest install https://github.com/org/monorepo/tree/main/skills/plan
132
164
  "internal": "https://gitlab.company.com"
133
165
  },
134
166
  "defaults": {
135
- "installDir": ".skills"
167
+ "installDir": ".skills",
168
+ "targetAgents": ["cursor", "claude-code"],
169
+ "installMode": "symlink"
136
170
  }
137
171
  }
138
172
  ```
@@ -158,12 +192,34 @@ Skills are installed to `.skills/` by default and can be integrated with any age
158
192
  | Windsurf | `.windsurf/skills/` |
159
193
  | GitHub Copilot | `.github/skills/` |
160
194
 
195
+ ## Publishing Skills
196
+
197
+ > **Note:** Publishing requires a private registry deployment. This feature is not available for public use yet.
198
+
199
+ Publish your skills to the registry for others to use:
200
+
201
+ ```bash
202
+ # Login to the registry
203
+ reskill login
204
+
205
+ # Validate without publishing (dry run)
206
+ reskill publish --dry-run
207
+
208
+ # Publish the skill
209
+ reskill publish
210
+ ```
211
+
212
+ For detailed publishing guidelines, see the [CLI Specification](./docs/cli-spec.md#publish).
213
+
161
214
  ## Environment Variables
162
215
 
163
- | Variable | Description | Default |
164
- | ------------------- | ---------------------- | ------------------ |
216
+ | Variable | Description | Default |
217
+ | -------- | ----------- | ------- |
165
218
  | `RESKILL_CACHE_DIR` | Global cache directory | `~/.reskill-cache` |
166
- | `DEBUG` | Enable debug logging | - |
219
+ | `RESKILL_TOKEN` | Auth token (takes precedence over ~/.reskillrc) | - |
220
+ | `RESKILL_REGISTRY` | Default registry URL | `https://registry.reskill.dev` |
221
+ | `DEBUG` | Enable debug logging | - |
222
+ | `NO_COLOR` | Disable colored output | - |
167
223
 
168
224
  ## Development
169
225
 
@@ -180,6 +236,9 @@ pnpm build
180
236
  # Run tests
181
237
  pnpm test
182
238
 
239
+ # Run integration tests
240
+ pnpm test:integration
241
+
183
242
  # Type check
184
243
  pnpm typecheck
185
244
  ```
package/README.zh-CN.md CHANGED
@@ -28,11 +28,14 @@ npx reskill@latest list
28
28
  - **一键安装** — 从任意 Git 仓库一键安装 skill
29
29
  - **声明式配置** — `skills.json` + `skills.lock` 确保团队一致性
30
30
  - **灵活版本** — 精确版本、semver 范围、分支、commit
31
- - **多 Registry** — GitHub、GitLab、自建、私有仓库
31
+ - **多源支持** — GitHub、GitLab、自建仓库、HTTP/OSS 归档
32
32
  - **多 Agent** — Cursor、Claude Code、Codex、Windsurf、GitHub Copilot 等
33
+ - **Registry 支持** — 发布和共享 skills
33
34
 
34
35
  ## 安装
35
36
 
37
+ **环境要求：** Node.js >= 18.0.0
38
+
36
39
  ```bash
37
40
  npm install -g reskill # 全局安装
38
41
  npx reskill@latest <command> # 或直接使用 npx
@@ -40,17 +43,23 @@ npx reskill@latest <command> # 或直接使用 npx
40
43
 
41
44
  ## 命令
42
45
 
43
- | 命令 | 说明 |
44
- | --------------------- | ----------------------- |
45
- | `init` | 初始化 `skills.json` |
46
- | `install [skills...]` | 安装一个或多个 skills |
47
- | `list` | 列出已安装的 skills |
48
- | `info <skill>` | 查看 skill 详情 |
49
- | `update [skill]` | 更新 skills |
50
- | `outdated` | 检查过期的 skills |
51
- | `uninstall <skill>` | 卸载 skill |
52
- | `doctor` | 诊断环境并检查问题 |
53
- | `completion install` | 安装 Shell Tab 补全 |
46
+ | 命令 | 别名 | 说明 |
47
+ | ---- | ---- | ---- |
48
+ | `init` | - | 初始化 `skills.json` |
49
+ | `install [skills...]` | `i` | 安装一个或多个 skills |
50
+ | `list` | `ls` | 列出已安装的 skills |
51
+ | `info <skill>` | - | 查看 skill 详情 |
52
+ | `update [skill]` | `up` | 更新 skills |
53
+ | `outdated` | - | 检查过期的 skills |
54
+ | `uninstall <skill>` | `un`, `rm`, `remove` | 卸载 skill |
55
+ | `publish [path]` | `pub` | 发布 skill 到 registry ¹ |
56
+ | `login` | - | 登录 registry ¹ |
57
+ | `logout` | - | 登出 registry ¹ |
58
+ | `whoami` | - | 显示当前登录用户 ¹ |
59
+ | `doctor` | - | 诊断环境并检查问题 |
60
+
61
+ > ¹ Registry 相关命令（`publish`、`login`、`logout`、`whoami`）需要部署私有 registry 后才能使用，暂不对外开放。
62
+ | `completion install` | - | 安装 Shell Tab 补全 |
54
63
 
55
64
  ### 常用选项
56
65
 
@@ -60,17 +69,38 @@ npx reskill@latest <command> # 或直接使用 npx
60
69
  | `-g, --global` | `install`, `uninstall`, `list` | 全局安装/管理技能（用户目录） |
61
70
  | `-a, --agent <agents...>` | `install` | 指定目标 Agent（如 `cursor`, `claude-code`） |
62
71
  | `--mode <mode>` | `install` | 安装模式：`symlink`（默认）或 `copy` |
72
+ | `--all` | `install` | 安装到所有 Agent |
73
+ | `-y, --yes` | `install`, `uninstall`, `publish` | 跳过确认提示 |
74
+ | `-f, --force` | `install` | 强制重新安装 |
75
+ | `-j, --json` | `list`, `info`, `outdated`, `doctor` | JSON 格式输出 |
63
76
 
64
77
  运行 `reskill <command> --help` 查看完整选项和详细用法。
65
78
 
66
79
  ## 源格式
67
80
 
68
81
  ```bash
69
- # 基本格式
82
+ # GitHub 简写
70
83
  npx reskill@latest install github:user/skill@v1.0.0
84
+
85
+ # GitLab 简写
71
86
  npx reskill@latest install gitlab:group/skill@latest
87
+
88
+ # 完整 Git URL (HTTPS)
89
+ npx reskill@latest install https://github.com/user/skill.git
90
+
91
+ # 完整 Git URL (SSH)
92
+ npx reskill@latest install git@github.com:user/skill.git
93
+
94
+ # GitHub/GitLab 网页 URL（含分支和子路径）
95
+ npx reskill@latest install https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
96
+
97
+ # 自定义 Registry（自建 GitLab 等）
72
98
  npx reskill@latest install gitlab.company.com:team/skill@v1.0.0
73
- npx reskill@latest install https://github.com/user/repo/tree/main/path
99
+
100
+ # HTTP/OSS 归档
101
+ npx reskill@latest install https://example.com/skills/my-skill-v1.0.0.tar.gz
102
+ npx reskill@latest install oss://bucket/path/skill.tar.gz
103
+ npx reskill@latest install s3://bucket/path/skill.zip
74
104
 
75
105
  # 一次安装多个 skills
76
106
  npx reskill@latest install github:user/skill1 github:user/skill2@v1.0.0
@@ -95,15 +125,30 @@ npx reskill@latest install https://github.com/org/monorepo/tree/main/skills/plan
95
125
 
96
126
  **要求**：指定的目录必须包含符合 [Agent Skills 规范](https://agentskills.io) 的有效 `SKILL.md` 文件。
97
127
 
128
+ ### HTTP/OSS URL 支持
129
+
130
+ 支持从 HTTP/HTTPS URL 直接安装归档文件：
131
+
132
+ | 格式 | 示例 | 说明 |
133
+ | ---- | ---- | ---- |
134
+ | HTTPS URL | `https://example.com/skill.tar.gz` | 直接下载链接 |
135
+ | 阿里云 OSS | `https://bucket.oss-cn-hangzhou.aliyuncs.com/skill.tar.gz` | 阿里云 OSS URL |
136
+ | AWS S3 | `https://bucket.s3.amazonaws.com/skill.tar.gz` | AWS S3 URL |
137
+ | OSS 协议 | `oss://bucket/path/skill.tar.gz` | 阿里云 OSS 简写 |
138
+ | S3 协议 | `s3://bucket/path/skill.tar.gz` | AWS S3 简写 |
139
+
140
+ **支持的归档格式**：`.tar.gz`、`.tgz`、`.zip`、`.tar`
141
+
98
142
  ## 版本规范
99
143
 
100
- | 格式 | 示例 | 说明 |
101
- | -------- | ----------------- | ---------------- |
102
- | 精确版本 | `@v1.0.0` | 锁定到指定 tag |
103
- | 最新版本 | `@latest` | 获取最新 tag |
104
- | 范围版本 | `@^2.0.0` | semver 兼容 |
105
- | 分支 | `@branch:develop` | 指定分支 |
106
- | Commit | `@commit:abc1234` | 指定 commit hash |
144
+ | 格式 | 示例 | 说明 |
145
+ | ---- | ---- | ---- |
146
+ | 精确版本 | `@v1.0.0` | 锁定到指定 tag |
147
+ | 最新版本 | `@latest` | 获取最新 tag |
148
+ | 范围版本 | `@^2.0.0` | semver 兼容 (>=2.0.0 <3.0.0) |
149
+ | 分支 | `@branch:develop` | 指定分支 |
150
+ | Commit | `@commit:abc1234` | 指定 commit hash |
151
+ | (无) | - | 默认分支 (main) |
107
152
 
108
153
  ## 配置
109
154
 
@@ -119,7 +164,9 @@ npx reskill@latest install https://github.com/org/monorepo/tree/main/skills/plan
119
164
  "internal": "https://gitlab.company.com"
120
165
  },
121
166
  "defaults": {
122
- "installDir": ".skills"
167
+ "installDir": ".skills",
168
+ "targetAgents": ["cursor", "claude-code"],
169
+ "installMode": "symlink"
123
170
  }
124
171
  }
125
172
  ```
@@ -145,12 +192,34 @@ Skills 默认安装到 `.skills/`，可与任何 Agent 集成：
145
192
  | Windsurf | `.windsurf/skills/` |
146
193
  | GitHub Copilot | `.github/skills/` |
147
194
 
195
+ ## 发布 Skills
196
+
197
+ > **注意：** 发布功能需要部署私有 registry 后才能使用，暂不对外开放。
198
+
199
+ 将你的 skills 发布到 registry 供他人使用：
200
+
201
+ ```bash
202
+ # 登录 registry
203
+ reskill login
204
+
205
+ # 验证但不发布（预览模式）
206
+ reskill publish --dry-run
207
+
208
+ # 发布 skill
209
+ reskill publish
210
+ ```
211
+
212
+ 详细的发布指南请参考 [CLI 规范](./docs/cli-spec.md#publish)。
213
+
148
214
  ## 环境变量
149
215
 
150
- | 变量 | 说明 | 默认值 |
151
- | ------------------- | ------------ | ------------------ |
216
+ | 变量 | 说明 | 默认值 |
217
+ | ---- | ---- | ------ |
152
218
  | `RESKILL_CACHE_DIR` | 全局缓存目录 | `~/.reskill-cache` |
153
- | `DEBUG` | 启用调试日志 | - |
219
+ | `RESKILL_TOKEN` | 认证令牌（优先于 ~/.reskillrc） | - |
220
+ | `RESKILL_REGISTRY` | 默认 registry URL | `https://registry.reskill.dev` |
221
+ | `DEBUG` | 启用调试日志 | - |
222
+ | `NO_COLOR` | 禁用彩色输出 | - |
154
223
 
155
224
  ## 开发
156
225
 
@@ -167,6 +236,9 @@ pnpm build
167
236
  # 运行测试
168
237
  pnpm test
169
238
 
239
+ # 运行集成测试
240
+ pnpm test:integration
241
+
170
242
  # 类型检查
171
243
  pnpm typecheck
172
244
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "reskill",
3
- "version": "1.3.0",
3
+ "version": "1.3.1",
4
4
  "description": "AI Skills Package Manager - Git-based skills management for AI agents",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",