@topmindspace/topmind-skills 4.13.1 → 4.13.2

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 (20) hide show
  1. package/INSTALL.md +121 -274
  2. package/README.en.md +4 -4
  3. package/README.md +4 -4
  4. package/README.zh-CN.md +3 -162
  5. package/bin/install-skills.mjs +1 -1
  6. package/evals/evals.json +1 -1
  7. package/package.json +1 -1
  8. package/skills.md +2 -2
  9. package/topmind/SKILL.md +1 -1
  10. package/topmind-capture/SKILL.md +1 -1
  11. package/topmind-ledger/SKILL.md +1 -1
  12. package/topmind-loop/SKILL.md +1 -1
  13. package/topmind-maintain/SKILL.md +1 -1
  14. package/topmind-memory/SKILL.md +1 -1
  15. package/topmind-organize/SKILL.md +1 -1
  16. package/topmind-pack.json +1 -1
  17. package/topmind-wechat/SKILL.md +1 -1
  18. package/topmind-weread/SKILL.md +1 -1
  19. package/topmind-write/SKILL.md +1 -1
  20. package/topmind-x/SKILL.md +1 -1
package/INSTALL.md CHANGED
@@ -2,312 +2,113 @@
2
2
 
3
3
  [简体中文](./README.md) · [English](./README.en.md) · [产品](https://github.com/topmindspace/topmind)
4
4
 
5
- **Model (same idea as open Agent Skills / `npx skills`):**
6
-
7
- ```text
8
- 指定源（GitHub 仓库 / 本地路径 / Release）
9
- + 仓库即 pack 根（topmind-skills 无 monorepo 子目录）
10
- + 安装目标（host 的 skills 根目录）
11
- → 安装
12
- → 以后在同一目标上 update 升级
13
- ```
14
-
15
- ```text
16
- Source examples: topmindspace/topmind-skills . release:latest
17
- Path default: . (topmind-skills 仓根即 pack)
18
- Dest examples: $HOME/.claude/skills ./.claude/skills $HOME/.codex/skills
19
- ```
20
-
21
5
  Repository: https://github.com/topmindspace/topmind-skills
22
6
  npm: [`@topmindspace/topmind-skills`](https://www.npmjs.com/package/@topmindspace/topmind-skills)
23
7
  Daily entry after install: **`topmind`**
24
8
 
9
+ ```text
10
+ Source → install into host skills root → update later from the same source
11
+ Source: topmindspace/topmind-skills | . | release:latest
12
+ Dest: $HOME/.claude/skills | ./.claude/skills | $HOME/.codex/skills | …
13
+ ```
14
+
25
15
  ---
26
16
 
27
- ## 0. Via npm（推荐 · pack-aware · 含 shared/）
17
+ ## Quick start
28
18
 
29
19
  ```bash
30
- # 安装到 Claude Code 用户全局 skills
20
+ # npm（推荐 · pack-aware · 含 shared/）
31
21
  npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g
32
-
33
- # 升级（读 dest 回执，重新拉同一源）
34
22
  npx @topmindspace/topmind-skills update -g
35
23
 
36
- # 只看会装什么
37
- npx @topmindspace/topmind-skills list topmindspace/topmind-skills
38
-
39
- # 指定宿主 / 目标目录
40
- npx @topmindspace/topmind-skills add topmindspace/topmind-skills --host codex
41
- npx @topmindspace/topmind-skills add topmindspace/topmind-skills --dest ./.claude/skills
42
- ```
43
-
44
- 也可以全局安装 CLI：
24
+ # 社区 CLI（快速试用；不含 shared/）
25
+ npx skills add topmindspace/topmind-skills -g -y
45
26
 
46
- ```bash
47
- npm i -g @topmindspace/topmind-skills
48
- topmind-skills add topmindspace/topmind-skills -g
27
+ # 从 GitHub Release（离线 / 固定版本）
28
+ node bin/install-skills.mjs add release:latest -g
49
29
  ```
50
30
 
51
- > npm 包与 GitHub 仓库同一内容真源（`topmind-pack.json` 版本对齐）。
52
- > **GitHub skills 更新不会自动同步到 npm**——需要 bump 版本后 `npm publish`（或走 tag 触发的 Release 自动发布，见下文）。
53
-
54
- ---
55
-
56
- ## 0b. Via Desktop（推荐 · 探测 + 装/升/卸）
57
-
58
- 若已安装 **topmind Desktop**，不必先跑 CLI：
59
-
60
- 1. 打开 **设置 → 关于与更新 (About & updates)**
61
- 2. 查看已探测的 Agent 宿主（Claude Code · Codex · Hermes · OpenCode · CodeBuddy 等）
62
- 3. 对目标宿主点 **安装 / 升级 / 卸载**（优先全局 skills 根 + 回执；卸载只删托管条目，不动无关用户 skill）
63
- 4. 同一页还可：**准备剪藏扩展**（引导浏览器 Load unpacked）、**安装 Obsidian 插件**到当前工作区 vault
64
-
65
- 独立 CLI / pack 路径仍然有效（无 Desktop 时用本节后续命令）。宿主探测与装机逻辑在 Desktop 内为纯 FS，与本脚本语义对齐。
31
+ 已装 **topmind Desktop** 时也可在 **设置 → 关于与更新** 里对探测到的宿主一键安装 / 升级 / 卸载。
66
32
 
67
33
  ---
68
34
 
69
- ## Publishing to skills.sh & Open Agent Skills Registry
70
-
71
- **skills.sh**（与 `npx skills` 工具网络）采用基于 **GitHub 公开仓库的直连索引机制**。将本仓库的 Skills 发布并公开到 `skills.sh` 无需传统 npm publish，步骤如下：
72
-
73
- 1. **规范校验与打包**：
74
- 确保技能文件符合 Agent Skills 规范（`SKILL.md` 包含 YAML frontmatter、Use when / Do NOT 边界、行数 <500）：
75
- ```bash
76
- npm run pack:skills
77
- npm test
78
- ```
79
- 2. **Push 至 GitHub Public 仓库**：
80
- ```bash
81
- git add .
82
- git commit -m "feat(skills): update skills definitions"
83
- git push origin main
84
- ```
85
- 3. **发布 Tag & Release（推荐）**：
86
- ```bash
87
- npm run versions # 真源 stamp；全量 tag 用 Desktop 版本
88
- git tag v<desktop-version>
89
- git push origin v<desktop-version>
90
- ```
91
- 4. **生态发现与在线安装**：
92
- 发布后，全球开发者即可通过以下方式发现与安装：
93
- - **npm（推荐）**：`npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g`
94
- - **CLI 直接索引**：`npx skills add topmindspace/topmind-skills -g -y`
95
- - **查看目录**：`npx skills add topmindspace/topmind-skills -l`
96
- - **网页版浏览**：访问 `https://skills.sh/topmindspace/topmind-skills`
97
- - **npm 包页**：https://www.npmjs.com/package/@topmindspace/topmind-skills
98
-
99
- ---
35
+ ## Installers
100
36
 
101
- ## Publishing to npm（@topmindspace/topmind-skills）
37
+ ### A. npm / Pack-aware（推荐）
102
38
 
103
- 包名：[`@topmindspace/topmind-skills`](https://www.npmjs.com/package/@topmindspace/topmind-skills)
104
- Org：`topmindspace` · 访问级别：`public` · 版本真源：`topmind-pack.json`（须与 `package.json` `version` 一致）
39
+ 装齐 skill 目录 + `shared/` + `topmind-pack.json`，保证 `../shared/*.md` 渐进披露可用。
105
40
 
106
41
  ```bash
107
- # 1) 同步版本（package.json + topmind-pack.json + 各 SKILL.md）
108
- npm test
109
-
110
- # 2) 发布（需 npmjs 登录；scoped public 包）
111
- npm publish --access public
112
- # package.json 已配置 publishConfig.access=public，直接 npm publish 亦可
113
-
114
- # 3) 验证
115
- npm view @topmindspace/topmind-skills
116
- npx @topmindspace/topmind-skills --help
117
- ```
118
-
119
- ### GitHub 更新后 npm 会自动更新吗？
120
-
121
- **不会。** GitHub 仓库 push / skills 内容变更 **不会** 自动发布到 npmjs。
122
-
123
- | 渠道 | 触发 | 是否自动 |
124
- |------|------|----------|
125
- | GitHub 仓库 / skills.sh | `git push` | 是（直连索引） |
126
- | GitHub Release | push tag `v*` | 是（CI 打包 Release） |
127
- | npm `@topmindspace/topmind-skills` | `npm publish` | **否**（需手动，或依赖下述 tag 自动发布） |
42
+ # 无需 clone
43
+ npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g
44
+ npx @topmindspace/topmind-skills update -g
45
+ npx @topmindspace/topmind-skills list topmindspace/topmind-skills
128
46
 
129
- 若要在打 tag 发 Release 时 **自动同步 npm**：
47
+ # 全局 CLI
48
+ npm i -g @topmindspace/topmind-skills
49
+ topmind-skills add topmindspace/topmind-skills -g
130
50
 
131
- 1. 在 GitHub 仓库 Secrets 配置 `NPM_TOKEN`（Automation 类型 token，来自 npmjs → Access Tokens）
132
- 2. Release workflow 会在创建 GitHub Release 后执行 `npm publish`
133
- 3. 流程：改 skills → 同步 bump `package.json` + `topmind-pack.json` + 各 `SKILL.md` 版本 → commit → `git tag vX.Y.Z && git push origin vX.Y.Z` → CI 自动发 GitHub Release **并** publish npm
51
+ # 指定宿主 / 目标
52
+ npx @topmindspace/topmind-skills add topmindspace/topmind-skills --host codex
53
+ npx @topmindspace/topmind-skills add topmindspace/topmind-skills --dest ./.claude/skills
134
54
 
135
- 没有 `NPM_TOKEN` 时，npm 发布步骤会跳过，不影响 GitHub Release。
55
+ # 源码仓内
56
+ npm run add -- topmindspace/topmind-skills -g
57
+ npm run update -- --dest $HOME/.claude/skills
58
+ npm run list -- topmindspace/topmind-skills
136
59
 
137
- ---
60
+ # 本地目录 / symlink 热更新
61
+ node bin/install-skills.mjs add . --mode symlink --dest $HOME/.claude/skills
138
62
 
139
- ## Two installers (pick one)
63
+ # Release zip
64
+ node bin/install-skills.mjs add release:latest -g
65
+ ```
140
66
 
141
- > 优先用上文 **§0 Via npm**（`npx @topmindspace/topmind-skills …`）——它就是 B 的 pack-aware 安装器，且自动带上 `shared/`。下面 A/B 说明底层两种安装路径。
67
+ 私有仓：`export GH_TOKEN=…`（或 `GITHUB_TOKEN`）后再 `add`。
142
68
 
143
- ### A. Community CLI — `npx skills`（和开源 skills 生态一致）
69
+ ### B. Community CLI — `npx skills`
144
70
 
145
- 已验证：本仓库可被直接发现 pack 内全部 skill（含可选 weread / x / ledger）。
71
+ 适用于 Claude Code / Cursor / Codex / OpenCode 等认 Agent Skills 目录布局的 host。
146
72
 
147
73
  ```bash
148
- # 安装到用户全局（$HOME/.claude/skills 等，按 agent 探测）
149
74
  npx skills add topmindspace/topmind-skills -g -y
150
-
151
- # 只装部分
152
75
  npx skills add topmindspace/topmind-skills -g -y -s topmind -s topmind-capture
153
-
154
- # 升级
155
76
  npx skills update -g -y
156
-
157
- # 列出仓库里有什么（不装）
158
77
  npx skills add topmindspace/topmind-skills -l
159
78
  ```
160
79
 
161
- 适用：Claude Code / Cursor / Codex / OpenCode 等认 Agent Skills 目录布局的 host。
162
-
163
- #### 关于 “Failed to install 9 / PromptScript”
164
-
165
- `npx skills add … -g` **多数已经成功**。日志里先有：
166
-
167
- ```text
168
- ◇ Installed 10 skills
169
- ✓ $HOME/.agents/skills/topmind (+ symlink → Claude Code / Codex / …)
170
- ```
171
-
172
- 末尾的 `Failed to install 9` **只针对 PromptScript**：该 host **不支持 global 安装**，不是 topmind 包损坏。可忽略，或不要装 PromptScript。
173
-
174
- 验收：
175
-
176
- ```bash
177
- ls $HOME/.agents/skills/topmind/SKILL.md
178
- ls $HOME/.claude/skills/topmind # 常为 symlink → $HOME/.agents/skills/topmind
179
- ```
180
-
181
- #### 社区 CLI 不会装 `shared/`（重要）
182
-
183
- 社区 CLI 只复制含 `SKILL.md` 的目录。topmind skill 内有 `../shared/*.md` 渐进披露链接，**缺 `shared/` 时子文档打不开**。
184
-
185
- 这是开放标准「单 skill 目录」与 topmind **pack 级 shared** 的已知差异。加载契约见 [`shared/host-loading.md`](./shared/host-loading.md)。
186
-
187
- 装完社区 CLI 后**务必**再跑 pack-aware（或手动拷 shared）：
80
+ **注意：社区 CLI 不会装 `shared/`。** topmind skill 有 `../shared/*.md` 链接，缺了会打不开子文档。装完后请再跑一次 pack-aware（或手动拷 `shared/`）：
188
81
 
189
82
  ```bash
190
- # ① 推荐：pack-aware 安装器（带 shared/ + topmind-pack.json）
191
- # 通用根（npx skills 主目录）
192
- node bin/install-skills.mjs add topmindspace/topmind-skills --dest $HOME/.agents/skills
193
- # 或 Claude 默认根
194
- node bin/install-skills.mjs add topmindspace/topmind-skills -g
195
-
196
- # ② 或手动把 monorepo / Release 包里的 shared 放到同级
197
- mkdir -p $HOME/.agents/skills
83
+ npx @topmindspace/topmind-skills add topmindspace/topmind-skills --dest $HOME/.agents/skills
84
+ # 或
198
85
  cp -R /path/to/topmind-skills/shared $HOME/.agents/skills/shared
199
86
  ```
200
87
 
201
- #### 其他 Host 也能装
202
-
203
- | Host 类型 | 做法 |
204
- |-----------|------|
205
- | Claude Code / Cursor / Codex / OpenCode | 目录布局 = Agent Skills：`{skillsRoot}/{name}/SKILL.md` |
206
- | 只认单路径 | symlink 整个 pack 根或 pack-aware 装到 host skills 根 |
207
- | MCP-only 宿主 | Skills 仍是 Markdown 指令；确定性命令可另接 UTR MCP（可选） |
208
- | 无 skill 系统 | 把 `topmind/SKILL.md` 当 system 片段粘贴；shared 按链接手动附上 |
209
-
210
- **Discovery**：Host 应只预加载各 skill 的 `name`+`description`（≤1024 字符）。
211
- **Activation**：匹配任务后再读完整 `SKILL.md`。
212
- **Resources**：需要时再读 `shared/` 与 `references/`。
213
-
214
- ### Zip 加载报 `SKILL.md not found`？
215
-
216
- topmind Release 包是 **多 skill 组合包**，不是单目录 skill：
217
-
218
- ```text
219
- topmind-skills-<ver>.zip
220
- └── topmind-skills-<ver>/
221
- ├── SKILL.md ← 根入口 = router
222
- ├── topmind/SKILL.md ← 推荐日常入口
223
- ├── topmind-capture/…
224
- └── shared/
225
- ```
226
-
227
- | Host 行为 | 正确处理 |
228
- |-----------|----------|
229
- | 解压 zip 后在根找 `SKILL.md` | 用包内根 `SKILL.md`（router） |
230
- | 扫描 `*/SKILL.md` 多 skill | 装全部 `topmind*` 目录 + `shared/` |
231
- | 社区 `npx skills add` | 从 GitHub 仓根装 skill 目录（不依赖 zip 根） |
232
-
233
- `skills.md` 是 **包索引**（人类可读），不是 Agent Skills 标准的 `SKILL.md` 替代名——两者并存，不要把 `skills.md` 改成唯一入口。
234
-
235
- ### B. Pack-aware 安装器 — `bin/install-skills.mjs`（推荐给 topmind）
236
-
237
- 会装齐 **skill 目录 + `shared/` + `topmind-pack.json` + …**，保证 `../shared/*.md` 渐进披露链接可用。
238
-
239
- ```bash
240
- # ① 指定仓库（默认 path=skills，装到 Claude 用户目录）
241
- node bin/install-skills.mjs add topmindspace/topmind-skills -g
242
-
243
- # ② 指定仓库 + 自定义 monorepo 子路径 + 自定义目标
244
- node bin/install-skills.mjs add topmindspace/topmind-skills \
245
- --dest $HOME/.claude/skills
246
-
247
- # ③ 装到「当前项目」而不是用户全局
248
- node bin/install-skills.mjs add topmindspace/topmind-skills \
249
- --dest ./.claude/skills
250
-
251
- # ④ 本地 monorepo / 任意目录当源
252
- node bin/install-skills.mjs add ./skills --dest $HOME/.claude/skills
253
- node bin/install-skills.mjs add ./skills --mode symlink --dest $HOME/.claude/skills
254
-
255
- # ⑤ 从 Release zip（有 topmind-skills-*.zip 时）
256
- node bin/install-skills.mjs add release:latest -g
257
-
258
- # ⑥ 升级（读目标目录里的回执，重新拉同一源）
259
- node bin/install-skills.mjs update --dest $HOME/.claude/skills
260
-
261
- # ⑦ 只看会装什么
262
- node bin/install-skills.mjs list topmindspace/topmind-skills
263
- ```
264
-
265
- 根脚本别名：
266
-
267
- ```bash
268
- npm run add -- topmindspace/topmind-skills -g
269
- npm run update -- --dest $HOME/.claude/skills
270
- npm run list -- topmindspace/topmind-skills
271
- ```
272
-
273
- 或直接用 npm 包 CLI（无需 clone）：
274
-
275
- ```bash
276
- npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g
277
- ```
278
-
279
- 私有仓：
280
-
281
- ```bash
282
- export GH_TOKEN=... # 或 GITHUB_TOKEN
283
- node bin/install-skills.mjs add topmindspace/topmind-skills -g
284
- ```
88
+ 日志末尾若出现 `Failed to install 9` 且指向 **PromptScript**，是该 host 不支持 global 安装，可忽略；topmind 本身已装上。
285
89
 
286
90
  ---
287
91
 
288
- ## Source 写法
92
+ ## Source / options
289
93
 
290
94
  | Source | 含义 |
291
95
  |--------|------|
292
96
  | `topmindspace/topmind-skills` | GitHub `owner/repo`，默认分支，pack 在仓根 |
293
- | `topmindspace/topmind-skills@v*` | 指定 ref / tag（版本见 `topmind-pack.json`） |
97
+ | `topmindspace/topmind-skills@v*` | 指定 ref / tag |
294
98
  | `https://github.com/topmindspace/topmind-skills.git` | 任意 git URL |
295
- | `./skills` / 绝对路径 | 本地 pack 根（含 `topmind-pack.json` 或 `*/SKILL.md`） |
99
+ | `./` / 绝对路径 | 本地 pack 根 |
296
100
  | `release:latest` | GitHub Release 里的 `topmind-skills-*.zip` |
297
101
 
298
102
  | Option | 含义 |
299
103
  |--------|------|
300
- | `--path <subdir>` | 仓库内 pack 子目录（默认 `.` 仓根） |
301
104
  | `--dest <dir>` | 安装目标 = host 的 skills 根 |
302
105
  | `-g` / `--global` | dest → `$HOME/.claude/skills` |
303
106
  | `--host codex` 等 | 换默认 dest |
304
107
  | `--mode symlink` | 仅本地源；开发时热更新 |
305
- | `--skill topmind` | 只装列出的 skill id（可重复） |
306
- | `--locale en-US` | 安装 locale overlay（回退到 `topmind_LOCALE` 环境变量）。**当前未随包提供任何 overlay**——技能正文以 zh-CN 为准，`--locale` 会回退到中文正文，不是英文版技能。 |
307
-
308
- ---
108
+ | `--skill topmind` | 只装列出的 skill id |
109
+ | `--locale en-US` | locale overlay（当前未提供 overlay，回退中文正文） |
309
110
 
310
- ## Host destinations
111
+ ### Host destinations
311
112
 
312
113
  | Host | 典型 dest | 写法 |
313
114
  |------|-----------|------|
@@ -316,54 +117,100 @@ node bin/install-skills.mjs add topmindspace/topmind-skills -g
316
117
  | Hermes | `$HOME/.hermes/skills` | `--host hermes` |
317
118
  | OpenCode | 项目 skills 路径 / config `skills.paths` | `--host opencode` 或见 `integrations/opencode/` |
318
119
 
319
- `install-targets/*.json` 描述各 host 契约（无硬编码本机绝对路径）。
120
+ 无 skill 系统的 host：把 `topmind/SKILL.md` 当 system 片段粘贴，`shared/` 按链接手动附上。
320
121
 
321
122
  ---
322
123
 
323
- ## Update 原理
124
+ ## Update
324
125
 
325
- 安装后在 dest 写入：
326
-
327
- ```text
328
- {dest}/.topmind-skills-install.json
329
- ```
330
-
331
- 里面记录了 `source` / `path` / `version`。之后只需：
126
+ 安装后 dest 会写入 `{dest}/.topmind-skills-install.json`（记录 `source` / `path` / `version`）：
332
127
 
333
128
  ```bash
129
+ npx @topmindspace/topmind-skills update -g
130
+ # 或
334
131
  node bin/install-skills.mjs update --dest <同一 dest>
132
+ # 社区 CLI
133
+ npx skills update -g -y
335
134
  ```
336
135
 
337
- 就会按原 source 再拉一遍并覆盖（升级）。
338
-
339
- 社区 CLI 对应：
136
+ 装完结构：
340
137
 
341
- ```bash
342
- npx skills update -g -y
138
+ ```text
139
+ {dest}/
140
+ ├── topmind/SKILL.md # 日常唯一入口
141
+ ├── topmind-*/
142
+ ├── shared/
143
+ ├── topmind-pack.json
144
+ └── .topmind-skills-install.json
343
145
  ```
344
146
 
345
147
  ---
346
148
 
347
- ## 装完长什么样
149
+ ## Zip 加载报 `SKILL.md not found`？
150
+
151
+ Release 包是 **多 skill 组合包**：
348
152
 
349
153
  ```text
350
- $HOME/.claude/skills/ # 或你指定的 --dest
351
- ├── topmind/SKILL.md # 日常唯一入口
352
- ├── topmind-capture/
353
- ├── topmind-organize/
354
- ├── …
355
- ├── shared/ # pack-aware 安装器会带上
356
- ├── topmind-pack.json
357
- └── .topmind-skills-install.json
154
+ topmind-skills-<ver>.zip
155
+ └── topmind-skills-<ver>/
156
+ ├── SKILL.md ← 根入口 = router
157
+ ├── topmind/SKILL.md ← 推荐日常入口
158
+ ├── topmind-*/
159
+ └── shared/
358
160
  ```
359
161
 
360
- 在 host 里调用 **`topmind`**。子 skill 是模块，不是并列产品入口。
162
+ | Host 行为 | 正确处理 |
163
+ |-----------|----------|
164
+ | 在 zip 根找 `SKILL.md` | 用包内根 `SKILL.md`（router） |
165
+ | 扫描 `*/SKILL.md` | 装全部 `topmind*` 目录 + `shared/` |
166
+ | `npx skills add` | 从 GitHub 仓根装（不依赖 zip 根） |
167
+
168
+ `skills.md` 是包索引，不是 `SKILL.md` 的替代名。
361
169
 
362
170
  ---
363
171
 
364
- ## OpenCode（可选）
172
+ ## 发布（GitHub Release + npm）
365
173
 
366
- 示例：`integrations/opencode/opencode.example.json` — 用 `skills.paths` 指向本仓根或已安装目录。
174
+ 版本真源：`topmind-pack.json`（须与 `package.json` `version`、各 `SKILL.md` / `evals` 一致）。
175
+
176
+ ```bash
177
+ # 1) 同步 bump 版本后校验
178
+ npm test
179
+ npm run pack # 可选：本地 dist 产物
180
+
181
+ # 2) 提交并打 tag（推荐发版方式）
182
+ git add . && git commit -m "chore: topmind-skills x.y.z"
183
+ git tag vX.Y.Z
184
+ git push origin main vX.Y.Z
185
+ ```
186
+
187
+ push tag `v*` 后 CI 自动：
188
+
189
+ 1. 测试 + 打包
190
+ 2. 创建 GitHub Release（附 zip / tar.gz / manifest / SHA256SUMS / latest.json）
191
+ 3. `npm publish` → [`@topmindspace/topmind-skills`](https://www.npmjs.com/package/@topmindspace/topmind-skills)（需仓库 Secret `NPM_TOKEN`，Automation token）
192
+ 4. **只保留最近 2 个 GitHub Release**，更旧的 Release 与 tag 会被删除
193
+
194
+ | 渠道 | 触发 | 自动 |
195
+ |------|------|------|
196
+ | GitHub 仓库 / skills.sh | `git push` | 是（直连索引） |
197
+ | GitHub Release | tag `v*` | 是 |
198
+ | npm | tag `v*`（有 `NPM_TOKEN`） | 是 |
199
+
200
+ 手动兜底（无 CI 时）：
201
+
202
+ ```bash
203
+ npm publish --access public
204
+ ```
205
+
206
+ ### skills.sh
207
+
208
+ 公开 GitHub 仓即可被 `npx skills` / [skills.sh](https://skills.sh/topmindspace/topmind-skills) 索引，无需额外注册：
209
+
210
+ ```bash
211
+ npx skills add topmindspace/topmind-skills -g -y
212
+ npx skills add topmindspace/topmind-skills -l
213
+ ```
367
214
 
368
215
  ---
369
216
 
@@ -371,4 +218,4 @@ $HOME/.claude/skills/ # 或你指定的 --dest
371
218
 
372
219
  - Skills 是 Markdown 指令；不信任的 fork 先审再装。
373
220
  - API Key 不要写进 skill 文件。
374
- - 安装器只写 `--dest`，不改 engine 仓库（除非 dest 故意指过去）。
221
+ - 安装器只写 `--dest`，不改其他目录。
package/README.en.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Portable AI skill pack: the same content contract on Claude Code / Codex / OpenCode / Hermes and other hosts.
4
4
 
5
- [简体中文](README.md) · [English](README.en.md) · [Product](https://github.com/topmindspace/topmind) · [Install](./INSTALL.md) · [Publish to skills.sh](./INSTALL.md#publishing-to-skillssh--open-agent-skills-registry) · [npm](https://www.npmjs.com/package/@topmindspace/topmind-skills)
5
+ [简体中文](README.md) · [English](README.en.md) · [Product](https://github.com/topmindspace/topmind) · [Install](./INSTALL.md) · [npm](https://www.npmjs.com/package/@topmindspace/topmind-skills)
6
6
 
7
7
  ```bash
8
8
  # 1) npm (recommended · pack-aware · includes shared/)
@@ -93,7 +93,7 @@ degradation: ../shared/capability-degradation.md
93
93
  ---
94
94
  ```
95
95
 
96
- Enforced by `skills/tests/package-manifest.test.mjs`. One pack JSON; no per-skill second manifest. Full schema: [`../SKILL-ARCHITECTURE.md`](../SKILL-ARCHITECTURE.md).
96
+ Enforced by `tests/package-manifest.test.mjs`. One pack JSON ([`topmind-pack.json`](./topmind-pack.json)); no per-skill second manifest.
97
97
 
98
98
  ---
99
99
 
@@ -136,7 +136,7 @@ Do not hardcode absolute paths — infer `workspace_root` from the host or ask.
136
136
  5. **参考资料定位**
137
137
  6. **大类命名稳定**（rename via migration）
138
138
 
139
- Full rules: [`../PROJECT-MODEL.md`](../PROJECT-MODEL.md) §3.
139
+ Full rules: [`shared/project-model-brief.md`](./shared/project-model-brief.md).
140
140
 
141
141
  ---
142
142
 
@@ -160,4 +160,4 @@ Full rules: [`../PROJECT-MODEL.md`](../PROJECT-MODEL.md) §3.
160
160
  Packaged skill directories (7 core + 2 optional connectors + optional ledger + optional wechat sub-skill) can be symlinked/copied into Claude Code, Codex, OpenCode, Hermes, and similar hosts.
161
161
  Prefer the pack-aware installer so `shared/` and `topmind-pack.json` stay intact — see [`INSTALL.md`](./INSTALL.md).
162
162
 
163
- Host adapters must **not** change content truth, add parallel daily entries, or store content in agent runtime state. See [`../PRODUCT-BOUNDARIES.md`](../PRODUCT-BOUNDARIES.md).
163
+ Host adapters must **not** change content truth, add parallel daily entries, or store content in agent runtime state. See [`shared/capability-degradation.md`](./shared/capability-degradation.md).
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  可移植 AI 技能包：在 Claude Code / Codex / OpenCode / Hermes 等 Host 上使用同一套内容约定。
4
4
 
5
- [简体中文](README.md) · [English](README.en.md) · [产品总览](https://github.com/topmindspace/topmind) · [安装与发布](./INSTALL.md) · [发布到 skills.sh](./INSTALL.md#publishing-to-skillssh--open-agent-skills-registry) · [npm](https://www.npmjs.com/package/@topmindspace/topmind-skills)
5
+ [简体中文](README.md) · [English](README.en.md) · [产品总览](https://github.com/topmindspace/topmind) · [安装与发布](./INSTALL.md) · [npm](https://www.npmjs.com/package/@topmindspace/topmind-skills)
6
6
 
7
7
  ```bash
8
8
  # 1) npm（推荐 · pack-aware · 含 shared/）
@@ -93,7 +93,7 @@ degradation: ../shared/capability-degradation.md
93
93
  ---
94
94
  ```
95
95
 
96
- 由 `skills/tests/package-manifest.test.mjs` 强制校验。一个 pack JSON，无 per-skill 第二清单。完整 schema：[`../SKILL-ARCHITECTURE.md`](../SKILL-ARCHITECTURE.md)。
96
+ 由 `tests/package-manifest.test.mjs` 强制校验。一个 pack JSON（[`topmind-pack.json`](./topmind-pack.json)），无 per-skill 第二清单。
97
97
 
98
98
  ---
99
99
 
@@ -136,7 +136,7 @@ degradation: ../shared/capability-degradation.md
136
136
  5. **参考资料定位**
137
137
  6. **大类命名稳定**（rename via migration）
138
138
 
139
- 完整规则：[`../PROJECT-MODEL.md`](../PROJECT-MODEL.md) §3。
139
+ 完整规则：[`shared/project-model-brief.md`](./shared/project-model-brief.md)。
140
140
 
141
141
  ---
142
142
 
@@ -164,4 +164,4 @@ degradation: ../shared/capability-degradation.md
164
164
  npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g
165
165
  ```
166
166
 
167
- Host 适配器**不得**改变内容真源、新增并列日常入口，或把内容存进 agent 运行态。见 [`../PRODUCT-BOUNDARIES.md`](../PRODUCT-BOUNDARIES.md)。
167
+ Host 适配器**不得**改变内容真源、新增并列日常入口，或把内容存进 agent 运行态。见 [`shared/capability-degradation.md`](./shared/capability-degradation.md)。
package/README.zh-CN.md CHANGED
@@ -1,163 +1,4 @@
1
- # topmind Skills
1
+ # topmind Skills（简体中文）
2
2
 
3
- 可移植 AI 技能包：在 Claude Code / Codex / OpenCode / Hermes 等 Host 上使用同一套内容约定。
4
-
5
- [简体中文](README.md) · [English](README.en.md) · [产品总览](https://github.com/topmindspace/topmind) · [安装与发布](./INSTALL.md) · [发布到 skills.sh](./INSTALL.md#publishing-to-skillssh--open-agent-skills-registry) · [npm](https://www.npmjs.com/package/@topmindspace/topmind-skills)
6
-
7
- ```bash
8
- # 1) npm（推荐 · pack-aware · 含 shared/）
9
- npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g
10
- # 升级
11
- npx @topmindspace/topmind-skills update -g
12
-
13
- # 2) 社区 CLI（快速试用；可能不含 shared/）
14
- npx skills add topmindspace/topmind-skills -g -y
15
-
16
- # 3) Pack-aware 安装器（源码仓内）
17
- npm run add -- topmindspace/topmind-skills -g
18
- npm run update -- --dest $HOME/.claude/skills
19
-
20
- # 4) 从 GitHub Release 装（离线/固定版本）
21
- node bin/install-skills.mjs add release:latest -g
22
- # 或下载 topmind-skills-<ver>.zip 后：
23
- # node bin/install-skills.mjs add ./unpacked --dest $HOME/.claude/skills
24
- ```
25
-
26
- **版本与清单真源：** [`topmind-pack.json`](./topmind-pack.json)（`npm run versions`）。
27
- 各 `SKILL.md` 的 `version` **必须**等于 pack 版本。
28
-
29
- ---
30
-
31
- ## 结构
32
-
33
- ```text
34
- topmind-skills/ # pack 根 = 仓库根
35
- ├── topmind/ # 唯一日常入口（router）
36
- ├── topmind-capture|organize|write|memory|maintain|loop/
37
- ├── topmind-weread|x/ # 可选连接器
38
- ├── topmind-ledger/ # 可选记账（记忆平面账本）
39
- ├── topmind-wechat/ # 可选公众号 write 子技能（不是并列入口）
40
- ├── shared/ # 写回回执 · 降级 · 捕获 …
41
- ├── install-targets/ # Host 安装形状
42
- ├── evals/evals.json
43
- ├── bin/install-skills.mjs # pack-aware 安装器（含 shared/）
44
- ├── scripts/build-pack.mjs
45
- └── topmind-pack.json # 版本真源
46
- ```
47
-
48
- | 类型 | 模块 |
49
- |------|------|
50
- | **入口** | `topmind` only |
51
- | **动作** | capture · organize · write · memory · maintain · loop |
52
- | **连接器** | weread · x（可选） |
53
- | **可选** | wechat（公众号 write 子技能）· ledger（记账 · 记忆平面账本） |
54
-
55
- > 子 skill 触发词只服务 Host 路由，**不是**第二前台入口。
56
-
57
- ---
58
-
59
- ## 产品契约
60
-
61
- ```text
62
- User experience: capture-first
63
- Data organization: category-first + topic-emerges
64
- Content truth: topmind-workspace/categories-and-topics
65
- Capability model: action-first
66
- Save settings: auto | confirm
67
- Safety model: reversible by default
68
- ```
69
-
70
- 日常入口只暴露 `topmind`。Host 会话状态不得成为 topmind 内容真源。
71
- 本 pack **不要求 Desktop**。**UTR 可选** — 没有 UTR 时用 Host 文件工具。
72
-
73
- 工作流：`收进来 -> 继续做 -> 交付/沉淀 -> 找回/调整`
74
- （用户说「收一下」「记一下」「整理」「写成稿」「跑一遍 loop」— router 推断类别 / 专题 / 动作。）
75
-
76
- ---
77
-
78
- ## SKILL.md frontmatter
79
-
80
- ```yaml
81
- ---
82
- name: <kebab-case-id> # required; matches directory name
83
- version: <pack.version> # required; = topmind-pack.json version
84
- description: >- # required; Use when + Do not use
85
- …
86
- action_category: capture # skill taxonomy (not user note category)
87
- triggers: [...]
88
- entrypoint: false # only topmind router is true
89
- author: TopMindSpace
90
- license: MIT
91
- homepage: https://github.com/topmindspace/topmind-skills
92
- degradation: ../shared/capability-degradation.md
93
- ---
94
- ```
95
-
96
- 由 `skills/tests/package-manifest.test.mjs` 强制校验。一个 pack JSON，无 per-skill 第二清单。完整 schema：[`../SKILL-ARCHITECTURE.md`](../SKILL-ARCHITECTURE.md)。
97
-
98
- ---
99
-
100
- ## 工作区契约
101
-
102
- ```text
103
- {workspace-root}/
104
- ├── topmind.yaml # contract v4
105
- ├── memory/ # profile.md · periodic/ · topics/ · todo.md · 可选 ledgers/
106
- ├── .topmind/ # rebuildable machine state
107
- ├── 00-Inbox/ # role: buffer (live dir name)
108
- ├── 10-动态/ … # categories (template-driven)
109
- ├── 88-交付/ or 88-Delivery/ # role: delivery
110
- └── 99-归档/ or 99-Archive/ # role: system
111
- ```
112
-
113
- 专题：
114
-
115
- ```text
116
- {category}/{YYYY-theme}/
117
- ├── topic.md # optional
118
- ├── *.md # notes at topic root
119
- └── images/ # optional
120
- ```
121
-
122
- 尚无专题时，散篇放在 `{category}/{note}.md`。
123
-
124
- **不要创建（已废弃）：** 默认 `outline.md` / `setting.md` / `style.md`；`project_type` frontmatter；专题内嵌套 `notes/` 或 `outputs/`；顶层 `projects/`；`YYYY-类型-项目名` 命名。
125
-
126
- **类别：** 运行时发现 `{NN-Name}/` + `topmind.yaml` v4（`categories.extensions` / `categories.overrides` 含 `hidden`）。共享解析器：引擎 `lib/workspace-model.mjs`。优先按角色路由，不要写死 `10-` / `20-` 编号。
127
-
128
- 不要硬编码绝对路径 — 从 Host 推断 `workspace_root`，或向用户询问。
129
-
130
- ### 6 条核心规约
131
-
132
- 1. **大类不重叠**
133
- 2. **专题自然涌现**
134
- 3. **动态类特殊**（默认平铺）
135
- 4. **兜底类清理**（约 30 天）
136
- 5. **参考资料定位**
137
- 6. **大类命名稳定**（rename via migration）
138
-
139
- 完整规则：[`../PROJECT-MODEL.md`](../PROJECT-MODEL.md) §3。
140
-
141
- ---
142
-
143
- ## 行为规则
144
-
145
- - 先捕获；不要因为分类不完美而挡住简单保存
146
- - 信号足够强时自动路由；否则走 **role:buffer**（现场 Inbox 目录，不要只写死 `00-Inbox/`）
147
- - 专题不清时，散篇放在大类根
148
- - 每次写入返回回执（路径、路由原因、下一步）
149
- - `source_type`: `user-original` | `external-capture` | `ai-derived`
150
- - UTR 可选 — Host 文件工具遵守同一契约
151
- - 保存设置协议：`writeback_mode: auto | confirm`
152
- - 锁定/定稿文件 → 修订副本（`文章 - 修订版.md`），不要原地自动改
153
- - 本 pack 不要求 Desktop
154
- - **复合纪律（不改结构）：** organize 把综合写回磁盘；write 先读可选 `topic.md`；memory 仅在明确确认后写；capture 从不改 `topic.md`；**不要**硬造 `INDEX.md` / 平行 wiki 树（见 `shared/project-model-brief.md`）
155
-
156
- ---
157
-
158
- ## 安装目标
159
-
160
- 已打包的 skill 目录（7 个核心 + 2 个可选连接器 + 可选记账）可以符号链接或复制到 Claude Code、Codex、OpenCode、Hermes 等。
161
- 优先使用 pack-aware 安装器，保证 `shared/` 与 `topmind-pack.json` 完整 — 见 [`INSTALL.md`](./INSTALL.md)。
162
-
163
- Host 适配器**不得**改变内容真源、新增并列日常入口，或把内容存进 agent 运行态。见 [`../PRODUCT-BOUNDARIES.md`](../PRODUCT-BOUNDARIES.md)。
3
+ 中文文档请直接看 **[README.md](./README.md)**。
4
+ English: [README.en.md](./README.en.md) · Install & publish: [INSTALL.md](./INSTALL.md)
package/bin/install-skills.mjs CHANGED
@@ -390,7 +390,7 @@ async function materializeFromRelease(tag, workDir) {
390
390
  } else {
391
391
  release = await fetchJson(`https://api.github.com/repos/${DEFAULT_OWNER_REPO}/releases/tags/${tag}`);
392
392
  }
393
- if (!release) fail("no GitHub release found — use owner/repo source or publish pack:skills");
393
+ if (!release) fail("no GitHub release found — use owner/repo source or publish a v* release tag");
394
394
  const assets = release.assets || [];
395
395
  const zip =
396
396
  assets.find((a) => /^topmind-skills-.*\.zip$/i.test(a.name)) ||
package/evals/evals.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "skill_name": "topmind",
3
3
  "daily_entry": "topmind",
4
- "version": "4.13.1",
4
+ "version": "4.13.2",
5
5
  "evals": [
6
6
  {
7
7
  "id": 1,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@topmindspace/topmind-skills",
3
- "version": "4.13.1",
3
+ "version": "4.13.2",
4
4
  "description": "topmind Agent Skills pack — portable markdown skills for capture, organize, write, memory, maintain, loop.",
5
5
  "type": "module",
6
6
  "license": "MIT",
package/skills.md CHANGED
@@ -31,9 +31,9 @@
31
31
  1. **唯一前台入口**：AI Agent 日常激活只需推荐 `topmind`。
32
32
  2. **渐进式披露 (Progressive Disclosure)**：Discovery (`name+description`) → Activation (`SKILL.md`) → Deep Procedures (`shared/` / `references/`)。
33
33
  3. **文件系统即真源**：不引入独立的数据库或 Agent state 依赖。
34
- 4. **遵从 6 条核心规约**：详见根目录 [`PROJECT-MODEL.md`](../PROJECT-MODEL.md)。
34
+ 4. **遵从 6 条核心规约**：见 [`shared/project-model-brief.md`](./shared/project-model-brief.md)。
35
35
 
36
36
  👉 **详细架构、Frontmatter Schema 与安装方法请参阅**：
37
37
  - [Skills README](./README.md)（简体中文） · [English](./README.en.md)
38
38
  - [多 Host 安装教程 (INSTALL.md)](./INSTALL.md)
39
- - [根目录架构契约 (SKILL-ARCHITECTURE.md)](../SKILL-ARCHITECTURE.md)
39
+ - Pack 真源：[`topmind-pack.json`](./topmind-pack.json)
package/topmind/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: topmind
3
- version: 4.13.1
3
+ version: 4.13.2
4
4
  description: >-
5
5
  topmind 总入口与多意图路由（类别/专题/笔记/交付）。Use when 用户说 topmind、意图模糊、或需要
6
6
  收→整→写 分步。单意图明确时直接用 topmind-capture|organize|write|memory|maintain|loop|weread|x|ledger|wechat。
package/topmind-capture/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: topmind-capture
3
- version: 4.13.1
3
+ version: 4.13.2
4
4
  description: >-
5
5
  把链接、摘录、随手记收进动态周期本、Inbox 或专题。Use when 记一下、收进、剪藏、保存链接、capture、save URL/idea。
6
6
  Do NOT use for 整理本周、出稿、写我的情况、doctor/loop、微信读书、X.
package/topmind-ledger/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: topmind-ledger
3
- version: 4.13.1
3
+ version: 4.13.2
4
4
  description: >-
5
5
  通用记账到记忆平面（默认个人/自己账本，用户自建账本与分类）。Use when 记账、记一笔、花了、存入、查看账单、账户余额。
6
6
  Do NOT use for 记一下到动态、待办、微信读书、发推、Feishu/lark-cli.
package/topmind-loop/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: topmind-loop
3
- version: 4.13.1
3
+ version: 4.13.2
4
4
  description: >-
5
5
  可中断的工作区语义巡检（走专题/Inbox，.loop 断点续跑）。Use when 跑一遍 loop、巡检、整体体检、复盘、
6
6
  继续 loop、audit。Do NOT use for 快速 doctor（→maintain）、单专题整理、捕获、写作、仅记忆.
package/topmind-maintain/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: topmind-maintain
3
- version: 4.13.1
3
+ version: 4.13.2
4
4
  description: >-
5
5
  确定性体检/清理/结构修复/回执恢复。Use when 快速体检、诊断、doctor、清理、修复、workspace check。
6
6
  Do NOT use for 整体巡检 loop、内容整理、捕获、写作、记忆.
package/topmind-memory/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: topmind-memory
3
- version: 4.13.1
3
+ version: 4.13.2
4
4
  description: >-
5
5
  更新「我的情况」或周期反思。Use when 记住这个、更新我的情况、加到专题记忆、沉淀结论。
6
6
  Do NOT use for 捕获、仅总结（→organize）、整理本周正文、出稿、开/并专题、doctor/loop.
package/topmind-organize/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: topmind-organize
3
- version: 4.13.1
3
+ version: 4.13.2
4
4
  description: >-
5
5
  整理本周动态、专题内整理/研究/分析/路由 Inbox。Use when 整理本周、整理、分析、研究、对比、总结要点、organize、summarize。
6
6
  Do NOT use for 首次捕获、最终出稿、仅写我的情况、快速 doctor、全库 loop.
package/topmind-pack.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "label": "topmind",
5
5
  "description": "topmind skill pack: single daily entry topmind + progressive disclosure (shared/ + references/), Agent Skills open-standard aligned, capture-first template-driven categories, optional weread/x connectors and optional ledger (记账). File-system-first content truth; UTR optional.",
6
6
  "daily_entry": "topmind",
7
- "version": "4.13.1",
7
+ "version": "4.13.2",
8
8
  "updated": "2026-09-24",
9
9
  "license": "MIT",
10
10
  "locales": {
package/topmind-wechat/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: topmind-wechat
3
- version: 4.13.1
3
+ version: 4.13.2
4
4
  description: >-
5
5
  公众号文章全生命周期子技能（write 族）：交付包、审校改写、质量三关、状态同步、微信内联排版与发布清单。
6
6
  支持 forward（底稿→公众号）、reverse（选题原创→回推）、站外拉取（在线精选站→reverse+pending）三条路径；
package/topmind-weread/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: topmind-weread
3
- version: 4.13.1
3
+ version: 4.13.2
4
4
  description: >-
5
5
  同步微信读书划线/想法/统计到专题。Use when 微信读书、划线同步、weread、读书笔记。
6
6
  Do NOT use for 普通 URL 捕获、仅整理、出稿、X.
package/topmind-write/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: topmind-write
3
- version: 4.13.1
3
+ version: 4.13.2
4
4
  description: >-
5
5
  写作/润色/出稿到专题或交付层（role:delivery）。Use when 写、起草、续写、润色、出稿、交付、write、draft、deliver。
6
6
  Do NOT use for 仅捕获、仅结构整理、只写记忆、doctor/loop、社交连接器.
package/topmind-x/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: topmind-x
3
- version: 4.13.1
3
+ version: 4.13.2
4
4
  description: >-
5
5
  X/Twitter：归档/搜索（Bearer）、发帖（xurl）、Agent 可用官方 MCP。Use when 发推、推特、twitter、x.com。
6
6
  Do NOT use for 微信读书、非 X 捕获、doctor、长文交付.