@workskills/getskill 2.0.0 → 3.0.0

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.
package/EXAMPLES.md CHANGED
@@ -2,32 +2,44 @@
2
2
 
3
3
  > 当前版本基于 `getskill.work` 静态索引 + ZIP 包下载,提供**搜索、下载(安装)、更新**三大核心功能,全部**无需 Git、无需登录**。
4
4
 
5
- ## 场景 1: 搜索并安装技能
5
+ ## 场景 1: 搜索技能 → Agent 判断 → 安装/更新
6
+
7
+ > `search` 只返回候选技能与简介(含本地安装状态),**不会自动安装任何技能**。
8
+ > 由 Agent 根据简介判断需要哪个技能,再自行执行 `install` / `update` 命令。
6
9
 
7
10
  ```bash
8
- # 搜索技能
9
- $ getskill search pdf
11
+ # 第一步: 搜索技能,把候选列表与简介返回给 Agent
12
+ $ getskill search pdf-toolkit
10
13
 
11
14
  找到 1 个技能:
12
15
 
13
- 1. pdf-extract (v1.0.0)
14
- 描述: 从 PDF 文件中提取文本和表格
16
+ 1. pdf-toolkit (v1.0.0)
17
+ 描述: PDF 文档处理技能:提取文本、合并拆分、页面旋转与加水印。
15
18
  分类: 文档处理
16
- 下载: https://getskill.work/skills/pdf-extract.zip
19
+ 下载: https://getskill.work/skills/pdf-toolkit.zip
20
+ 本地: 未安装(如需要: getskill install pdf-toolkit)
21
+
22
+ 提示: search 只返回候选技能与简介,不会自动安装任何技能。
23
+ 请由 Agent 根据简介判断需要哪个技能,再自行执行 getskill install / update <技能名称>。
17
24
 
18
- # 安装技能
19
- $ getskill install pdf-extract
25
+ # 第二步: Agent 阅读简介后自行判断——
26
+ # - 简介匹配任务需求且未安装 → 执行 install
27
+ # - 已安装但版本落后(suggested_action=update)→ 执行 update
28
+ # - 同版本已安装(suggested_action=skip)或简介不匹配 → 不执行任何命令
20
29
 
21
- 下载技能: pdf-extract...
22
- 下载技能包: https://getskill.work/skills/pdf-extract.zip
23
- 下载完成 (173410 bytes),正在解压...
24
- 技能包已解压: ~/.openclaw/skills-cache/pdf-extract
25
- 技能 pdf-extract (v1.0.0) 安装成功!
30
+ # 第三步: Agent 决定安装后,自行运行安装命令
31
+ $ getskill install pdf-toolkit
26
32
 
33
+ 下载技能: pdf-toolkit...
34
+ 下载技能包: https://getskill.work/skills/pdf-toolkit.zip
35
+ 下载完成 (1025 bytes),正在解压...
36
+ 技能 pdf-toolkit (v1.0.0) 安装成功!
37
+
38
+ 目标 Agent: claude (Claude Code)
27
39
  技能已安装到 skills 目录:
28
- - ~/.openclaw/skills/pdf-extract
40
+ - ~/.claude/skills/pdf-toolkit
29
41
 
30
- 本地缓存: ~/.openclaw/skills-cache/pdf-extract
42
+ 本地缓存: ~/.getskill/cache/pdf-toolkit/pdf-toolkit
31
43
  已安装版本: 1.0.0
32
44
  ```
33
45
 
@@ -37,46 +49,54 @@ $ getskill install pdf-extract
37
49
  # 列出已安装的技能
38
50
  $ getskill list
39
51
 
40
- 本地已安装的技能 (1):
41
- 1. pdf-extract
52
+ 本地已安装的技能 (1) · Agent: claude · 目录: ~/.claude/skills
53
+ 1. pdf-toolkit
42
54
 
43
55
  # 检查更新(版本比较)
44
- $ getskill update pdf-extract
56
+ $ getskill update pdf-toolkit
45
57
 
46
- 正在更新技能: pdf-extract...
58
+ 正在更新技能: pdf-toolkit...
47
59
  发现新版本: 1.0.0 -> 1.1.0
48
- 下载技能包: https://getskill.work/skills/pdf-extract.zip
60
+ 下载技能包: https://getskill.work/skills/pdf-toolkit.zip
49
61
  下载完成 (175000 bytes),正在解压...
50
- 技能 pdf-extract 更新成功!
62
+ 技能 pdf-toolkit 更新成功!
51
63
 
64
+ 目标 Agent: claude (Claude Code)
52
65
  技能已更新到 skills 目录:
53
- - ~/.openclaw/skills/pdf-extract
66
+ - ~/.claude/skills/pdf-toolkit
54
67
  当前版本: 1.1.0
55
68
 
56
69
  # 已是最新时
57
- $ getskill update pdf-extract
70
+ $ getskill update pdf-toolkit
58
71
 
59
- 正在更新技能: pdf-extract...
60
- 技能 pdf-extract 已是最新版本 (1.1.0),无需更新
72
+ 正在更新技能: pdf-toolkit...
73
+ 技能 pdf-toolkit 已是最新版本 (1.1.0),无需更新
61
74
 
62
75
  技能已是最新版本 (v1.1.0),无需更新。
63
76
 
64
- # 批量更新所有已安装技能
77
+ # 批量更新所有已安装技能(--prune 同时清理已下架技能的历史记录)
65
78
  $ getskill update --all
79
+ $ getskill update --all --prune
80
+
81
+ 批量更新完成:1/1 个技能成功。
66
82
 
67
83
  # 查看某个技能的安装状态
68
- $ getskill inspect pdf-extract
84
+ $ getskill inspect pdf-toolkit
69
85
 
70
- # 查看目录路径
86
+ # 查看 Agent 与目录路径
71
87
  $ getskill path
72
88
 
73
- 技能目录: ~/.openclaw/skills
74
- 缓存目录: ~/.openclaw/skills-cache
89
+ Agent: claude (Claude Code)
90
+ 技能目录: ~/.claude/skills
91
+ 缓存目录: ~/.getskill/cache
92
+ 配置文件: ~/.getskill/config.json
93
+ 状态文件: ~/.getskill/state.json
94
+ 站点地址: https://getskill.work
75
95
 
76
96
  # 清理 ZIP 下载/解压缓存
77
97
  $ getskill clean
78
98
 
79
- 已清理缓存目录: ~/.openclaw/skills-cache
99
+ 已清理缓存目录: ~/.getskill/cache
80
100
  ```
81
101
 
82
102
  ## 场景 3: JSON 输出与脚本集成
@@ -99,13 +119,19 @@ $ getskill search xlsx --json
99
119
  "version": "1.0.0",
100
120
  "category": "文档处理",
101
121
  "author": "Anthropic",
102
- "size": 173410
122
+ "size": 173410,
123
+ "installed": false,
124
+ "installed_version": null,
125
+ "suggested_action": "install"
103
126
  }
104
127
  ]
105
128
  }
106
129
  ```
107
130
 
108
- 批量安装脚本:
131
+ Agent 集成建议:把 `--json` 结果(名称 + `description` + `suggested_action`)交给 Agent,
132
+ 由 Agent 判断需要哪个技能后再执行 `getskill install/update <名称>`;search 本身不安装任何技能。
133
+
134
+ 批量安装脚本(技能清单由人工/Agent 事先选定,而非直接安装全部搜索结果):
109
135
 
110
136
  ```bash
111
137
  #!/bin/bash
@@ -136,10 +162,12 @@ const getskill = require('@workskills/getskill');
136
162
  console.log('当前索引:', getskill.getBaseUrl());
137
163
 
138
164
  // 搜索技能(基于静态索引 data/skills.json)
165
+ // 只返回候选技能与简介(含 installed/suggested_action),不会安装任何技能
139
166
  const results = await getskill.searchSkills('pdf');
140
167
  console.log('搜索结果:', results);
141
168
 
142
- // 安装技能(下载 ZIP + 本地解压 + 复制)
169
+ // 由调用方/Agent 根据简介判断后,再决定是否安装
170
+ // (示例中假定已选定 pdf-extract;下载 ZIP + 本地解压 + 复制)
143
171
  const result = await getskill.downloadSkill('pdf-extract');
144
172
  console.log('安装成功:', result.files);
145
173
 
@@ -172,16 +200,43 @@ $ getskill search pdf
172
200
  提示: 尝试使用不同的关键词,或访问 https://getskill.work 查看所有可用技能
173
201
  ```
174
202
 
175
- ## 场景 6: 配置自定义索引地址
203
+ ## 场景 6: 切换 Agent / 自定义目录 / 自定义索引
176
204
 
177
205
  ```bash
178
- # 查看当前索引地址
206
+ # 查看当前生效配置(含来源)
179
207
  $ getskill config get
180
- 当前 BASE_URL: https://getskill.work
181
208
 
182
- # 设置自定义索引地址(需要同样提供 /data/skills.json 与 /skills/<id>.zip)
183
- $ getskill config set https://custom-index.example.com
184
- BASE_URL 已设置为: https://custom-index.example.com
209
+ base-url: https://getskill.work
210
+ 来源: 默认值,未保存,使用默认站点
211
+ agent: claude (Claude Code)
212
+ 来源: 自动识别,未保存,自动识别本机 Agent
213
+ skills-dir: ~/.claude/skills
214
+ 来源: 自动识别,未单独保存,由 agent 推导
215
+ cache-dir: ~/.getskill/cache
216
+ 来源: 默认值,未保存,使用默认缓存目录
217
+ 配置文件: ~/.getskill/config.json
218
+ 状态文件: ~/.getskill/state.json
219
+
220
+ # 列出内置 Agent 预设
221
+ $ getskill agents
222
+
223
+ # 切换到其它 Agent(持久化)
224
+ $ getskill config set agent cursor
225
+ agent: cursor (Cursor)
226
+ 来源: 配置文件,已保存: cursor
227
+
228
+ # 任意 Agent:直接指定技能目录(持久化)
229
+ $ getskill config set skills-dir ~/.my-agent/skills
230
+
231
+ # 只对本次命令生效
232
+ $ getskill --agent codex install pdf-toolkit
233
+ $ getskill --skills-dir ~/.my-agent/skills install pdf-toolkit
234
+
235
+ # 删除配置项,恢复自动识别/默认值
236
+ $ getskill config unset agent
237
+
238
+ # 自定义索引地址(需要同样提供 /data/skills.json 与 /skills/<id>.zip)
239
+ $ getskill config set base-url https://custom-index.example.com
185
240
 
186
241
  # 通过环境变量临时覆盖
187
242
  $ GETSKILL_BASE_URL=https://another-index.com getskill search pdf
@@ -190,19 +245,21 @@ $ GETSKILL_BASE_URL=https://another-index.com getskill search pdf
190
245
  ## 场景 7: 目录结构查看
191
246
 
192
247
  ```bash
193
- $ tree ~/.openclaw
194
-
195
- ~/.openclaw/
196
- ├── skills/
197
- │ ├── pdf-extract/
198
- │ │ └── SKILL.md
199
- │ └── xlsx/
200
- │ └── SKILL.md
201
- └── skills-cache/
202
- ├── pdf-extract/ # 解压后的技能包内容
203
- │ └── SKILL.md
204
- └── xlsx/
205
- └── SKILL.md
248
+ $ tree ~/.getskill
249
+
250
+ ~/.getskill/
251
+ ├── config.json # 持久化配置
252
+ ├── state.json # 安装记录(技能名、版本、安装目录)
253
+ └── cache/
254
+ └── pdf-toolkit/ # ZIP 解压后的技能包内容
255
+ └── pdf-toolkit/
256
+ └── SKILL.md
257
+
258
+ $ tree ~/.claude/skills # 当前 Agent 的技能目录
259
+
260
+ ~/.claude/skills/
261
+ └── pdf-toolkit/
262
+ └── SKILL.md
206
263
  ```
207
264
 
208
265
  ## 常见问题
@@ -211,9 +268,13 @@ $ tree ~/.openclaw
211
268
 
212
269
  A: 不需要。搜索、安装、更新、卸载均通过 HTTP 直接下载 ZIP 并本地解压完成,全程不依赖 Git。
213
270
 
271
+ ### Q: 我用的 Agent 不在预设列表里怎么办?
272
+
273
+ A: 用 `getskill config set skills-dir <path>`、`getskill --skills-dir <path> ...` 或 `GETSKILL_SKILLS_DIR=<path>` 指定该 Agent 的技能目录即可。
274
+
214
275
  ### Q: 如何卸载技能?
215
276
 
216
- A: 使用 `getskill uninstall <技能名称>`,或直接删除 `~/.openclaw/skills/` 下对应目录。
277
+ A: 使用 `getskill uninstall <技能名称>`,或直接删除当前技能目录(`getskill path` 可查看)下对应的子目录。
217
278
 
218
279
  ### Q: 缓存目录可以删除吗?
219
280
 
@@ -222,3 +283,7 @@ A: 可以使用 `getskill clean` 清理缓存,下次安装/更新时会重新
222
283
  ### Q: 更新是如何判断的?
223
284
 
224
285
  A: 安装时会在本地记录技能版本;`update` 时拉取远端索引中的最新版本号进行比较,不一致才重新下载。
286
+
287
+ ### Q: `update --all` 提示某些技能“已跳过”是什么意思?
288
+
289
+ A: 说明这些技能已从索引中下架或改名,本地只剩下历史记录。执行 `getskill update --all --prune` 可以清理这些失效记录。