@topmindspace/topmind-skills 4.13.0 → 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 +128 -202
  2. package/README.en.md +13 -12
  3. package/README.md +18 -13
  4. package/README.zh-CN.md +3 -161
  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 +2 -2
  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,233 +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
6
+ npm: [`@topmindspace/topmind-skills`](https://www.npmjs.com/package/@topmindspace/topmind-skills)
22
7
  Daily entry after install: **`topmind`**
23
8
 
24
- ---
25
-
26
- ## 0. Via Desktop（推荐 · 探测 + 装/升/卸）
27
-
28
- 若已安装 **topmind Desktop**，不必先跑 CLI：
29
-
30
- 1. 打开 **设置 → 关于与更新 (About & updates)**
31
- 2. 查看已探测的 Agent 宿主（Claude Code · Codex · Hermes · OpenCode · CodeBuddy 等）
32
- 3. 对目标宿主点 **安装 / 升级 / 卸载**（优先全局 skills 根 + 回执；卸载只删托管条目，不动无关用户 skill）
33
- 4. 同一页还可：**准备剪藏扩展**（引导浏览器 Load unpacked）、**安装 Obsidian 插件**到当前工作区 vault
34
-
35
- 独立 CLI / pack 路径仍然有效（无 Desktop 时用本节后续命令）。宿主探测与装机逻辑在 Desktop 内为纯 FS，与本脚本语义对齐。
36
-
37
- ---
38
-
39
- ## Publishing to skills.sh & Open Agent Skills Registry
40
-
41
- **skills.sh**（与 `npx skills` 工具网络）采用基于 **GitHub 公开仓库的直连索引机制**。将本仓库的 Skills 发布并公开到 `skills.sh` 无需传统 npm publish，步骤如下：
42
-
43
- 1. **规范校验与打包**：
44
- 确保技能文件符合 Agent Skills 规范（`SKILL.md` 包含 YAML frontmatter、Use when / Do NOT 边界、行数 <500）：
45
- ```bash
46
- npm run pack:skills
47
- npm test
48
- ```
49
- 2. **Push 至 GitHub Public 仓库**：
50
- ```bash
51
- git add .
52
- git commit -m "feat(skills): update skills definitions"
53
- git push origin main
54
- ```
55
- 3. **发布 Tag & Release（推荐）**：
56
- ```bash
57
- npm run versions # 真源 stamp；全量 tag 用 Desktop 版本
58
- git tag v<desktop-version>
59
- git push origin v<desktop-version>
60
- ```
61
- 4. **生态发现与在线安装**：
62
- 发布后，全球开发者即可通过以下方式发现与安装：
63
- - **CLI 直接索引**：`npx skills add topmindspace/topmind-skills -g -y`
64
- - **查看目录**：`npx skills add topmindspace/topmind-skills -l`
65
- - **网页版浏览**：访问 `https://skills.sh/topmindspace/topmind-skills`
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
+ ```
66
14
 
67
15
  ---
68
16
 
69
- ## Two installers (pick one)
70
-
71
- ### A. Community CLI — `npx skills`（和开源 skills 生态一致）
72
-
73
- 已验证：本仓库可被直接发现 pack 内全部 skill（含可选 weread / x / ledger）。
17
+ ## Quick start
74
18
 
75
19
  ```bash
76
- # 安装到用户全局（$HOME/.claude/skills 等，按 agent 探测）
77
- npx skills add topmindspace/topmind-skills -g -y
78
-
79
- # 只装部分
80
- npx skills add topmindspace/topmind-skills -g -y -s topmind -s topmind-capture
81
-
82
- # 升级
83
- npx skills update -g -y
84
-
85
- # 列出仓库里有什么（不装）
86
- npx skills add topmindspace/topmind-skills -l
87
- ```
20
+ # npm（推荐 · pack-aware · 含 shared/）
21
+ npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g
22
+ npx @topmindspace/topmind-skills update -g
88
23
 
89
- 适用：Claude Code / Cursor / Codex / OpenCode 等认 Agent Skills 目录布局的 host。
90
-
91
- #### 关于 “Failed to install 9 / PromptScript”
92
-
93
- `npx skills add … -g` **多数已经成功**。日志里先有：
24
+ # 社区 CLI（快速试用；不含 shared/）
25
+ npx skills add topmindspace/topmind-skills -g -y
94
26
 
95
- ```text
96
- ◇ Installed 10 skills
97
- ✓ $HOME/.agents/skills/topmind (+ symlink → Claude Code / Codex / …)
27
+ # 从 GitHub Release（离线 / 固定版本）
28
+ node bin/install-skills.mjs add release:latest -g
98
29
  ```
99
30
 
100
- 末尾的 `Failed to install 9` **只针对 PromptScript**：该 host **不支持 global 安装**，不是 topmind 包损坏。可忽略，或不要装 PromptScript。
101
-
102
- 验收：
103
-
104
- ```bash
105
- ls $HOME/.agents/skills/topmind/SKILL.md
106
- ls $HOME/.claude/skills/topmind # 常为 symlink → $HOME/.agents/skills/topmind
107
- ```
31
+ 已装 **topmind Desktop** 时也可在 **设置 → 关于与更新** 里对探测到的宿主一键安装 / 升级 / 卸载。
108
32
 
109
- #### 社区 CLI 不会装 `shared/`（重要）
33
+ ---
110
34
 
111
- 社区 CLI 只复制含 `SKILL.md` 的目录。topmind skill 内有 `../shared/*.md` 渐进披露链接，**缺 `shared/` 时子文档打不开**。
35
+ ## Installers
112
36
 
113
- 这是开放标准「单 skill 目录」与 topmind **pack 级 shared** 的已知差异。加载契约见 [`shared/host-loading.md`](./shared/host-loading.md)。
37
+ ### A. npm / Pack-aware（推荐）
114
38
 
115
- 装完社区 CLI 后**务必**再跑 pack-aware（或手动拷 shared）：
39
+ 装齐 skill 目录 + `shared/` + `topmind-pack.json`，保证 `../shared/*.md` 渐进披露可用。
116
40
 
117
41
  ```bash
118
- # ① 推荐：pack-aware 安装器（带 shared/ + topmind-pack.json）
119
- # 通用根（npx skills 主目录）
120
- node bin/install-skills.mjs add topmindspace/topmind-skills --dest $HOME/.agents/skills
121
- # 或 Claude 默认根
122
- node bin/install-skills.mjs add topmindspace/topmind-skills -g
123
-
124
- # ② 或手动把 monorepo / Release 包里的 shared 放到同级
125
- mkdir -p $HOME/.agents/skills
126
- cp -R /path/to/topmind-skills/shared $HOME/.agents/skills/shared
127
- ```
128
-
129
- #### 其他 Host 也能装
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
130
46
 
131
- | Host 类型 | 做法 |
132
- |-----------|------|
133
- | Claude Code / Cursor / Codex / OpenCode | 目录布局 = Agent Skills：`{skillsRoot}/{name}/SKILL.md` |
134
- | 只认单路径 | symlink 整个 pack 根或 pack-aware 装到 host skills 根 |
135
- | MCP-only 宿主 | Skills 仍是 Markdown 指令；确定性命令可另接 UTR MCP（可选） |
136
- | 无 skill 系统 | 把 `topmind/SKILL.md` 当 system 片段粘贴；shared 按链接手动附上 |
47
+ # 全局 CLI
48
+ npm i -g @topmindspace/topmind-skills
49
+ topmind-skills add topmindspace/topmind-skills -g
137
50
 
138
- **Discovery**：Host 应只预加载各 skill 的 `name`+`description`（≤1024 字符）。
139
- **Activation**：匹配任务后再读完整 `SKILL.md`。
140
- **Resources**：需要时再读 `shared/` 与 `references/`。
51
+ # 指定宿主 / 目标
52
+ npx @topmindspace/topmind-skills add topmindspace/topmind-skills --host codex
53
+ npx @topmindspace/topmind-skills add topmindspace/topmind-skills --dest ./.claude/skills
141
54
 
142
- ### Zip 加载报 `SKILL.md not found`？
55
+ # 源码仓内
56
+ npm run add -- topmindspace/topmind-skills -g
57
+ npm run update -- --dest $HOME/.claude/skills
58
+ npm run list -- topmindspace/topmind-skills
143
59
 
144
- topmind Release 包是 **多 skill 组合包**，不是单目录 skill：
60
+ # 本地目录 / symlink 热更新
61
+ node bin/install-skills.mjs add . --mode symlink --dest $HOME/.claude/skills
145
62
 
146
- ```text
147
- topmind-skills-<ver>.zip
148
- └── topmind-skills-<ver>/
149
- ├── SKILL.md ← 根入口 = router
150
- ├── topmind/SKILL.md ← 推荐日常入口
151
- ├── topmind-capture/…
152
- └── shared/
63
+ # Release zip
64
+ node bin/install-skills.mjs add release:latest -g
153
65
  ```
154
66
 
155
- | Host 行为 | 正确处理 |
156
- |-----------|----------|
157
- | 解压 zip 后在根找 `SKILL.md` | 用包内根 `SKILL.md`（router） |
158
- | 扫描 `*/SKILL.md` 多 skill | 装全部 `topmind*` 目录 + `shared/` |
159
- | 社区 `npx skills add` | 从 GitHub 仓根装 skill 目录（不依赖 zip 根） |
160
-
161
- `skills.md` 是 **包索引**（人类可读），不是 Agent Skills 标准的 `SKILL.md` 替代名——两者并存，不要把 `skills.md` 改成唯一入口。
67
+ 私有仓：`export GH_TOKEN=…`（或 `GITHUB_TOKEN`）后再 `add`。
162
68
 
163
- ### B. Pack-aware 安装器 — `bin/install-skills.mjs`（推荐给 topmind）
69
+ ### B. Community CLI — `npx skills`
164
70
 
165
- 会装齐 **skill 目录 + `shared/` + `topmind-pack.json` + …**，保证 `../shared/*.md` 渐进披露链接可用。
71
+ 适用于 Claude Code / Cursor / Codex / OpenCode 等认 Agent Skills 目录布局的 host。
166
72
 
167
73
  ```bash
168
- # ① 指定仓库（默认 path=skills，装到 Claude 用户目录）
169
- node bin/install-skills.mjs add topmindspace/topmind-skills -g
170
-
171
- # ② 指定仓库 + 自定义 monorepo 子路径 + 自定义目标
172
- node bin/install-skills.mjs add topmindspace/topmind-skills \
173
- --dest $HOME/.claude/skills
174
-
175
- # ③ 装到「当前项目」而不是用户全局
176
- node bin/install-skills.mjs add topmindspace/topmind-skills \
177
- --dest ./.claude/skills
178
-
179
- # ④ 本地 monorepo / 任意目录当源
180
- node bin/install-skills.mjs add ./skills --dest $HOME/.claude/skills
181
- node bin/install-skills.mjs add ./skills --mode symlink --dest $HOME/.claude/skills
182
-
183
- # ⑤ 从 Release zip（有 topmind-skills-*.zip 时）
184
- node bin/install-skills.mjs add release:latest -g
185
-
186
- # ⑥ 升级（读目标目录里的回执，重新拉同一源）
187
- node bin/install-skills.mjs update --dest $HOME/.claude/skills
188
-
189
- # ⑦ 只看会装什么
190
- node bin/install-skills.mjs list topmindspace/topmind-skills
74
+ npx skills add topmindspace/topmind-skills -g -y
75
+ npx skills add topmindspace/topmind-skills -g -y -s topmind -s topmind-capture
76
+ npx skills update -g -y
77
+ npx skills add topmindspace/topmind-skills -l
191
78
  ```
192
79
 
193
- 根脚本别名：
80
+ **注意：社区 CLI 不会装 `shared/`。** topmind skill 有 `../shared/*.md` 链接，缺了会打不开子文档。装完后请再跑一次 pack-aware（或手动拷 `shared/`）：
194
81
 
195
82
  ```bash
196
- npm run install -- add topmindspace/topmind-skills -g
197
- npm run update -- --dest $HOME/.claude/skills
83
+ npx @topmindspace/topmind-skills add topmindspace/topmind-skills --dest $HOME/.agents/skills
84
+ # 或
85
+ cp -R /path/to/topmind-skills/shared $HOME/.agents/skills/shared
198
86
  ```
199
87
 
200
- 私有仓：
201
-
202
- ```bash
203
- export GH_TOKEN=... # 或 GITHUB_TOKEN
204
- node bin/install-skills.mjs add topmindspace/topmind-skills -g
205
- ```
88
+ 日志末尾若出现 `Failed to install 9` 且指向 **PromptScript**，是该 host 不支持 global 安装，可忽略；topmind 本身已装上。
206
89
 
207
90
  ---
208
91
 
209
- ## Source 写法
92
+ ## Source / options
210
93
 
211
94
  | Source | 含义 |
212
95
  |--------|------|
213
96
  | `topmindspace/topmind-skills` | GitHub `owner/repo`，默认分支，pack 在仓根 |
214
- | `topmindspace/topmind-skills@v*` | 指定 ref / tag（版本见 `topmind-pack.json`） |
97
+ | `topmindspace/topmind-skills@v*` | 指定 ref / tag |
215
98
  | `https://github.com/topmindspace/topmind-skills.git` | 任意 git URL |
216
- | `./skills` / 绝对路径 | 本地 pack 根（含 `topmind-pack.json` 或 `*/SKILL.md`） |
99
+ | `./` / 绝对路径 | 本地 pack 根 |
217
100
  | `release:latest` | GitHub Release 里的 `topmind-skills-*.zip` |
218
101
 
219
102
  | Option | 含义 |
220
103
  |--------|------|
221
- | `--path <subdir>` | 仓库内 pack 子目录（默认 `.` 仓根） |
222
104
  | `--dest <dir>` | 安装目标 = host 的 skills 根 |
223
105
  | `-g` / `--global` | dest → `$HOME/.claude/skills` |
224
106
  | `--host codex` 等 | 换默认 dest |
225
107
  | `--mode symlink` | 仅本地源；开发时热更新 |
226
- | `--skill topmind` | 只装列出的 skill id（可重复） |
227
- | `--locale en-US` | 安装 locale overlay（回退到 `topmind_LOCALE` 环境变量）。**当前未随包提供任何 overlay**——技能正文以 zh-CN 为准，`--locale` 会回退到中文正文，不是英文版技能。 |
108
+ | `--skill topmind` | 只装列出的 skill id |
109
+ | `--locale en-US` | locale overlay（当前未提供 overlay，回退中文正文） |
228
110
 
229
- ---
230
-
231
- ## Host destinations
111
+ ### Host destinations
232
112
 
233
113
  | Host | 典型 dest | 写法 |
234
114
  |------|-----------|------|
@@ -237,54 +117,100 @@ node bin/install-skills.mjs add topmindspace/topmind-skills -g
237
117
  | Hermes | `$HOME/.hermes/skills` | `--host hermes` |
238
118
  | OpenCode | 项目 skills 路径 / config `skills.paths` | `--host opencode` 或见 `integrations/opencode/` |
239
119
 
240
- `install-targets/*.json` 描述各 host 契约（无硬编码本机绝对路径）。
120
+ 无 skill 系统的 host：把 `topmind/SKILL.md` 当 system 片段粘贴，`shared/` 按链接手动附上。
241
121
 
242
122
  ---
243
123
 
244
- ## Update 原理
245
-
246
- 安装后在 dest 写入：
124
+ ## Update
247
125
 
248
- ```text
249
- {dest}/.topmind-skills-install.json
250
- ```
251
-
252
- 里面记录了 `source` / `path` / `version`。之后只需：
126
+ 安装后 dest 会写入 `{dest}/.topmind-skills-install.json`（记录 `source` / `path` / `version`）：
253
127
 
254
128
  ```bash
129
+ npx @topmindspace/topmind-skills update -g
130
+ # 或
255
131
  node bin/install-skills.mjs update --dest <同一 dest>
132
+ # 社区 CLI
133
+ npx skills update -g -y
256
134
  ```
257
135
 
258
- 就会按原 source 再拉一遍并覆盖（升级）。
259
-
260
- 社区 CLI 对应：
136
+ 装完结构：
261
137
 
262
- ```bash
263
- 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
264
145
  ```
265
146
 
266
147
  ---
267
148
 
268
- ## 装完长什么样
149
+ ## Zip 加载报 `SKILL.md not found`？
150
+
151
+ Release 包是 **多 skill 组合包**：
269
152
 
270
153
  ```text
271
- $HOME/.claude/skills/ # 或你指定的 --dest
272
- ├── topmind/SKILL.md # 日常唯一入口
273
- ├── topmind-capture/
274
- ├── topmind-organize/
275
- ├── …
276
- ├── shared/ # pack-aware 安装器会带上
277
- ├── topmind-pack.json
278
- └── .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/
279
160
  ```
280
161
 
281
- 在 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` 的替代名。
282
169
 
283
170
  ---
284
171
 
285
- ## OpenCode（可选）
172
+ ## 发布（GitHub Release + npm）
173
+
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
+ ```
286
186
 
287
- 示例：`integrations/opencode/opencode.example.json` — 用 `skills.paths` 指向本仓根或已安装目录。
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
+ ```
288
214
 
289
215
  ---
290
216
 
@@ -292,4 +218,4 @@ $HOME/.claude/skills/ # 或你指定的 --dest
292
218
 
293
219
  - Skills 是 Markdown 指令；不信任的 fork 先审再装。
294
220
  - API Key 不要写进 skill 文件。
295
- - 安装器只写 `--dest`，不改 engine 仓库（除非 dest 故意指过去）。
221
+ - 安装器只写 `--dest`，不改其他目录。
package/README.en.md CHANGED
@@ -2,21 +2,22 @@
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)
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
- # 1) Community CLI (fast try; may omit shared/)
8
+ # 1) npm (recommended · pack-aware · includes shared/)
9
+ npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g
10
+ # upgrade
11
+ npx @topmindspace/topmind-skills update -g
12
+
13
+ # 2) Community CLI (fast try; may omit shared/)
9
14
  npx skills add topmindspace/topmind-skills -g -y
10
15
 
11
- # 2) Pack-aware installer (recommended · includes shared/ · writes receipt)
12
- # From a topmind-skills checkout:
13
- npm run install -- add topmindspace/topmind-skills -g
16
+ # 3) Pack-aware installer (from a source checkout)
17
+ npm run add -- topmindspace/topmind-skills -g
14
18
  npm run update -- --dest $HOME/.claude/skills
15
19
 
16
- # Or without clone — run installer from GitHub:
17
- npx --yes github:topmindspace/topmind-skills install -g
18
-
19
- # 3) From GitHub Release (pinned version / offline)
20
+ # 4) From GitHub Release (pinned version / offline)
20
21
  node bin/install-skills.mjs add release:latest -g
21
22
  # or after downloading topmind-skills-<ver>.zip:
22
23
  # node bin/install-skills.mjs add ./unpacked --dest $HOME/.claude/skills
@@ -92,7 +93,7 @@ degradation: ../shared/capability-degradation.md
92
93
  ---
93
94
  ```
94
95
 
95
- 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.
96
97
 
97
98
  ---
98
99
 
@@ -135,7 +136,7 @@ Do not hardcode absolute paths — infer `workspace_root` from the host or ask.
135
136
  5. **参考资料定位**
136
137
  6. **大类命名稳定**（rename via migration）
137
138
 
138
- Full rules: [`../PROJECT-MODEL.md`](../PROJECT-MODEL.md) §3.
139
+ Full rules: [`shared/project-model-brief.md`](./shared/project-model-brief.md).
139
140
 
140
141
  ---
141
142
 
@@ -159,4 +160,4 @@ Full rules: [`../PROJECT-MODEL.md`](../PROJECT-MODEL.md) §3.
159
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.
160
161
  Prefer the pack-aware installer so `shared/` and `topmind-pack.json` stay intact — see [`INSTALL.md`](./INSTALL.md).
161
162
 
162
- 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,21 +2,22 @@
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)
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
- # 1) 社区 CLI（快速试用；可能不含 shared/）
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/）
9
14
  npx skills add topmindspace/topmind-skills -g -y
10
15
 
11
- # 2) Pack-aware 安装器（推荐生产 · 含 shared/ · 可写回执）
12
- # 在 topmind-skills 仓内：
13
- npm run install -- add topmindspace/topmind-skills -g
16
+ # 3) Pack-aware 安装器（源码仓内）
17
+ npm run add -- topmindspace/topmind-skills -g
14
18
  npm run update -- --dest $HOME/.claude/skills
15
19
 
16
- # 或不 clone，直接用 npx 跑 GitHub 上的安装器：
17
- npx --yes github:topmindspace/topmind-skills install -g
18
-
19
- # 3) 从 GitHub Release 装（离线/固定版本）
20
+ # 4) 从 GitHub Release 装（离线/固定版本）
20
21
  node bin/install-skills.mjs add release:latest -g
21
22
  # 或下载 topmind-skills-<ver>.zip 后：
22
23
  # node bin/install-skills.mjs add ./unpacked --dest $HOME/.claude/skills
@@ -92,7 +93,7 @@ degradation: ../shared/capability-degradation.md
92
93
  ---
93
94
  ```
94
95
 
95
- 由 `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 第二清单。
96
97
 
97
98
  ---
98
99
 
@@ -135,7 +136,7 @@ degradation: ../shared/capability-degradation.md
135
136
  5. **参考资料定位**
136
137
  6. **大类命名稳定**（rename via migration）
137
138
 
138
- 完整规则：[`../PROJECT-MODEL.md`](../PROJECT-MODEL.md) §3。
139
+ 完整规则：[`shared/project-model-brief.md`](./shared/project-model-brief.md)。
139
140
 
140
141
  ---
141
142
 
@@ -157,6 +158,10 @@ degradation: ../shared/capability-degradation.md
157
158
  ## 安装目标
158
159
 
159
160
  已打包的 skill 目录（7 个核心 + 2 个可选连接器 + 可选记账）可以符号链接或复制到 Claude Code、Codex、OpenCode、Hermes 等。
160
- 优先使用 pack-aware 安装器，保证 `shared/` 与 `topmind-pack.json` 完整 — 见 [`INSTALL.md`](./INSTALL.md)。
161
+ 优先使用 npm / pack-aware 安装器，保证 `shared/` 与 `topmind-pack.json` 完整 — 见 [`INSTALL.md`](./INSTALL.md)。
162
+
163
+ ```bash
164
+ npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g
165
+ ```
161
166
 
162
- 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,162 +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)
6
-
7
- ```bash
8
- # 1) 社区 CLI（快速试用；可能不含 shared/）
9
- npx skills add topmindspace/topmind-skills -g -y
10
-
11
- # 2) Pack-aware 安装器（推荐生产 · 含 shared/ · 可写回执）
12
- # 在 topmind-skills 仓内：
13
- npm run install -- add topmindspace/topmind-skills -g
14
- npm run update -- --dest $HOME/.claude/skills
15
-
16
- # 或不 clone，直接用 npx 跑 GitHub 上的安装器：
17
- npx --yes github:topmindspace/topmind-skills install -g
18
-
19
- # 3) 从 GitHub Release 装（离线/固定版本）
20
- node bin/install-skills.mjs add release:latest -g
21
- # 或下载 topmind-skills-<ver>.zip 后：
22
- # node bin/install-skills.mjs add ./unpacked --dest $HOME/.claude/skills
23
- ```
24
-
25
- **版本与清单真源：** [`topmind-pack.json`](./topmind-pack.json)（`npm run versions`）。
26
- 各 `SKILL.md` 的 `version` **必须**等于 pack 版本。
27
-
28
- ---
29
-
30
- ## 结构
31
-
32
- ```text
33
- topmind-skills/ # pack 根 = 仓库根
34
- ├── topmind/ # 唯一日常入口（router）
35
- ├── topmind-capture|organize|write|memory|maintain|loop/
36
- ├── topmind-weread|x/ # 可选连接器
37
- ├── topmind-ledger/ # 可选记账（记忆平面账本）
38
- ├── topmind-wechat/ # 可选公众号 write 子技能（不是并列入口）
39
- ├── shared/ # 写回回执 · 降级 · 捕获 …
40
- ├── install-targets/ # Host 安装形状
41
- ├── evals/evals.json
42
- ├── bin/install-skills.mjs # pack-aware 安装器（含 shared/）
43
- ├── scripts/build-pack.mjs
44
- └── topmind-pack.json # 版本真源
45
- ```
46
-
47
- | 类型 | 模块 |
48
- |------|------|
49
- | **入口** | `topmind` only |
50
- | **动作** | capture · organize · write · memory · maintain · loop |
51
- | **连接器** | weread · x（可选） |
52
- | **可选** | wechat（公众号 write 子技能）· ledger（记账 · 记忆平面账本） |
53
-
54
- > 子 skill 触发词只服务 Host 路由，**不是**第二前台入口。
55
-
56
- ---
57
-
58
- ## 产品契约
59
-
60
- ```text
61
- User experience: capture-first
62
- Data organization: category-first + topic-emerges
63
- Content truth: topmind-workspace/categories-and-topics
64
- Capability model: action-first
65
- Save settings: auto | confirm
66
- Safety model: reversible by default
67
- ```
68
-
69
- 日常入口只暴露 `topmind`。Host 会话状态不得成为 topmind 内容真源。
70
- 本 pack **不要求 Desktop**。**UTR 可选** — 没有 UTR 时用 Host 文件工具。
71
-
72
- 工作流：`收进来 -> 继续做 -> 交付/沉淀 -> 找回/调整`
73
- （用户说「收一下」「记一下」「整理」「写成稿」「跑一遍 loop」— router 推断类别 / 专题 / 动作。）
74
-
75
- ---
76
-
77
- ## SKILL.md frontmatter
78
-
79
- ```yaml
80
- ---
81
- name: <kebab-case-id> # required; matches directory name
82
- version: <pack.version> # required; = topmind-pack.json version
83
- description: >- # required; Use when + Do not use
84
- …
85
- action_category: capture # skill taxonomy (not user note category)
86
- triggers: [...]
87
- entrypoint: false # only topmind router is true
88
- author: TopMindSpace
89
- license: MIT
90
- homepage: https://github.com/topmindspace/topmind-skills
91
- degradation: ../shared/capability-degradation.md
92
- ---
93
- ```
94
-
95
- 由 `skills/tests/package-manifest.test.mjs` 强制校验。一个 pack JSON，无 per-skill 第二清单。完整 schema：[`../SKILL-ARCHITECTURE.md`](../SKILL-ARCHITECTURE.md)。
96
-
97
- ---
98
-
99
- ## 工作区契约
100
-
101
- ```text
102
- {workspace-root}/
103
- ├── topmind.yaml # contract v4
104
- ├── memory/ # profile.md · periodic/ · topics/ · todo.md · 可选 ledgers/
105
- ├── .topmind/ # rebuildable machine state
106
- ├── 00-Inbox/ # role: buffer (live dir name)
107
- ├── 10-动态/ … # categories (template-driven)
108
- ├── 88-交付/ or 88-Delivery/ # role: delivery
109
- └── 99-归档/ or 99-Archive/ # role: system
110
- ```
111
-
112
- 专题：
113
-
114
- ```text
115
- {category}/{YYYY-theme}/
116
- ├── topic.md # optional
117
- ├── *.md # notes at topic root
118
- └── images/ # optional
119
- ```
120
-
121
- 尚无专题时，散篇放在 `{category}/{note}.md`。
122
-
123
- **不要创建（已废弃）：** 默认 `outline.md` / `setting.md` / `style.md`；`project_type` frontmatter；专题内嵌套 `notes/` 或 `outputs/`；顶层 `projects/`；`YYYY-类型-项目名` 命名。
124
-
125
- **类别：** 运行时发现 `{NN-Name}/` + `topmind.yaml` v4（`categories.extensions` / `categories.overrides` 含 `hidden`）。共享解析器：引擎 `lib/workspace-model.mjs`。优先按角色路由，不要写死 `10-` / `20-` 编号。
126
-
127
- 不要硬编码绝对路径 — 从 Host 推断 `workspace_root`，或向用户询问。
128
-
129
- ### 6 条核心规约
130
-
131
- 1. **大类不重叠**
132
- 2. **专题自然涌现**
133
- 3. **动态类特殊**（默认平铺）
134
- 4. **兜底类清理**（约 30 天）
135
- 5. **参考资料定位**
136
- 6. **大类命名稳定**（rename via migration）
137
-
138
- 完整规则：[`../PROJECT-MODEL.md`](../PROJECT-MODEL.md) §3。
139
-
140
- ---
141
-
142
- ## 行为规则
143
-
144
- - 先捕获；不要因为分类不完美而挡住简单保存
145
- - 信号足够强时自动路由；否则走 **role:buffer**（现场 Inbox 目录，不要只写死 `00-Inbox/`）
146
- - 专题不清时，散篇放在大类根
147
- - 每次写入返回回执（路径、路由原因、下一步）
148
- - `source_type`: `user-original` | `external-capture` | `ai-derived`
149
- - UTR 可选 — Host 文件工具遵守同一契约
150
- - 保存设置协议：`writeback_mode: auto | confirm`
151
- - 锁定/定稿文件 → 修订副本（`文章 - 修订版.md`），不要原地自动改
152
- - 本 pack 不要求 Desktop
153
- - **复合纪律（不改结构）：** organize 把综合写回磁盘；write 先读可选 `topic.md`；memory 仅在明确确认后写；capture 从不改 `topic.md`；**不要**硬造 `INDEX.md` / 平行 wiki 树（见 `shared/project-model-brief.md`）
154
-
155
- ---
156
-
157
- ## 安装目标
158
-
159
- 已打包的 skill 目录（7 个核心 + 2 个可选连接器 + 可选记账）可以符号链接或复制到 Claude Code、Codex、OpenCode、Hermes 等。
160
- 优先使用 pack-aware 安装器，保证 `shared/` 与 `topmind-pack.json` 完整 — 见 [`INSTALL.md`](./INSTALL.md)。
161
-
162
- 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.0",
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.0",
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.0
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.0
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.0
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.0
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.0
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.0
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.0
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,8 +4,8 @@
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.0",
8
- "updated": "2026-09-23",
7
+ "version": "4.13.2",
8
+ "updated": "2026-09-24",
9
9
  "license": "MIT",
10
10
  "locales": {
11
11
  "default": "zh-CN",
package/topmind-wechat/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: topmind-wechat
3
- version: 4.13.0
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.0
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.0
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.0
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、长文交付.