@topmindspace/topmind-skills 4.13.1 → 4.13.3

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 (26) hide show
  1. package/INSTALL.md +160 -270
  2. package/README.en.md +15 -9
  3. package/README.md +17 -11
  4. package/README.zh-CN.md +3 -162
  5. package/bin/install-skills.mjs +447 -52
  6. package/evals/evals.json +1 -1
  7. package/install-targets/claude-code.json +8 -4
  8. package/install-targets/codex.json +8 -4
  9. package/install-targets/hermes.json +8 -4
  10. package/install-targets/mimocode.json +59 -0
  11. package/install-targets/opencode.json +8 -4
  12. package/install-targets/universal.json +58 -0
  13. package/package.json +5 -2
  14. package/skills.md +2 -2
  15. package/topmind/SKILL.md +1 -1
  16. package/topmind-capture/SKILL.md +1 -1
  17. package/topmind-ledger/SKILL.md +1 -1
  18. package/topmind-loop/SKILL.md +1 -1
  19. package/topmind-maintain/SKILL.md +1 -1
  20. package/topmind-memory/SKILL.md +1 -1
  21. package/topmind-organize/SKILL.md +1 -1
  22. package/topmind-pack.json +1 -1
  23. package/topmind-wechat/SKILL.md +1 -1
  24. package/topmind-weread/SKILL.md +1 -1
  25. package/topmind-write/SKILL.md +1 -1
  26. package/topmind-x/SKILL.md +1 -1
package/INSTALL.md CHANGED
@@ -2,373 +2,263 @@
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`):**
5
+ Repository: https://github.com/topmindspace/topmind-skills
6
+ npm: [`@topmindspace/topmind-skills`](https://www.npmjs.com/package/@topmindspace/topmind-skills)
7
+ Daily entry after install: **`topmind`**
6
8
 
7
9
  ```text
8
- 指定源（GitHub 仓库 / 本地路径 / Release）
9
- + 仓库即 pack 根（topmind-skills 无 monorepo 子目录）
10
- + 安装目标（host 的 skills 根目录）
11
- → 安装
12
- → 以后在同一目标上 update 升级
10
+ canonical <base>/.agents/skills ← pack body (one copy)
11
+ universal tools that read .agents/skills need nothing else
12
+ private Claude Code / MiMoCode / Hermes … ← relative symlink (or --copy)
13
13
  ```
14
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
- Repository: https://github.com/topmindspace/topmind-skills
22
- npm: [`@topmindspace/topmind-skills`](https://www.npmjs.com/package/@topmindspace/topmind-skills)
23
- Daily entry after install: **`topmind`**
15
+ 安装模型与开源生态 [`npx skills`](https://github.com/vercel-labs/skills) / [skills.sh](https://skills.sh) 对齐，与 `@topmindspace/tms-skills` 同一套机制。
24
16
 
25
17
  ---
26
18
 
27
- ## 0. Via npm（推荐 · pack-aware · 含 shared/）
19
+ ## Quick start
28
20
 
29
21
  ```bash
30
- # 安装到 Claude Code 用户全局 skills
22
+ # npm（推荐 · pack-aware · 含 shared/）
31
23
  npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g
32
-
33
- # 升级（读 dest 回执，重新拉同一源）
34
24
  npx @topmindspace/topmind-skills update -g
35
25
 
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：
26
+ # 社区 CLI（快速试用；不含 shared/ — 见下文）
27
+ npx skills add topmindspace/topmind-skills -g -y
45
28
 
46
- ```bash
47
- npm i -g @topmindspace/topmind-skills
48
- topmind-skills add topmindspace/topmind-skills -g
29
+ # 从 GitHub Release（离线 / 固定版本）
30
+ node bin/install-skills.mjs add release:latest -g
49
31
  ```
50
32
 
51
- > npm 包与 GitHub 仓库同一内容真源（`topmind-pack.json` 版本对齐）。
52
- > **GitHub skills 更新不会自动同步到 npm**——需要 bump 版本后 `npm publish`（或走 tag 触发的 Release 自动发布，见下文）。
33
+ 已装 **topmind Desktop** 时也可在 **设置 → 关于与更新** 里对探测到的宿主一键安装 / 升级 / 卸载。
53
34
 
54
35
  ---
55
36
 
56
- ## 0b. Via Desktop（推荐 · 探测 + 装/升/卸）
57
-
58
- 若已安装 **topmind Desktop**，不必先跑 CLI：
37
+ ## 安装模型（canonical + agents）
59
38
 
60
- 1. 打开 **设置 → 关于与更新 (About & updates)**
61
- 2. 查看已探测的 Agent 宿主（Claude Code · Codex · Hermes · OpenCode · CodeBuddy 等）
62
- 3. 对目标宿主点 **安装 / 升级 / 卸载**（优先全局 skills 根 + 回执；卸载只删托管条目，不动无关用户 skill）
63
- 4. 同一页还可：**准备剪藏扩展**（引导浏览器 Load unpacked）、**安装 Obsidian 插件**到当前工作区 vault
39
+ | 概念 | 路径 | 说明 |
40
+ |------|------|------|
41
+ | **Canonical** | `<base>/.agents/skills/` | 整包只存一份（project base = cwd，global base = `~`） |
42
+ | **Universal** | 就是 `.agents/skills` | Codex / Cursor / Gemini CLI / Warp / Zed… 项目级**直接读** |
43
+ | **Private** | `.claude/skills` · `.mimocode/skills` · `~/.codex/skills` … | 相对**软链**到 canonical（默认）；`--copy` 改为独立副本 |
64
44
 
65
- 独立 CLI / pack 路径仍然有效（无 Desktop 时用本节后续命令）。宿主探测与装机逻辑在 Desktop 内为纯 FS，与本脚本语义对齐。
45
+ 装完结构（global 示例）：
66
46
 
67
- ---
47
+ ```text
48
+ ~/.agents/skills/ ← canonical（真身 + receipt）
49
+ ├── topmind/SKILL.md ← 日常唯一入口
50
+ ├── topmind-*/
51
+ ├── shared/
52
+ ├── topmind-pack.json
53
+ └── .topmind-skills-install.json
68
54
 
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
55
+ ~/.claude/skills/topmind → ../../.agents/skills/topmind
56
+ ~/.claude/skills/shared → ../../.agents/skills/shared
57
+ ~/.config/mimocode/skills/topmind → ../../../.agents/skills/topmind
58
+ …
59
+ ```
98
60
 
99
- ---
61
+ `../shared/*.md` 渐进披露：在 canonical 内解析到 `~/.agents/skills/shared`；经软链进入时同样落在 canonical 的 `shared/`（相对链接指向同一真身）。
100
62
 
101
- ## Publishing to npm（@topmindspace/topmind-skills）
63
+ | 命令 | 作用 |
64
+ |------|------|
65
+ | `add <source>` | 默认 **matrix**：canonical + 已检测智能体 |
66
+ | `add … -g` / `-p` | 全局 `~/.agents/skills` / 项目 `./.agents/skills` |
67
+ | `add … -a claude-code -a mimocode` | 指定智能体（可多个；`'*'` 全部） |
68
+ | `add … --copy` | 私有目录独立副本（默认软链） |
69
+ | `add … --dest <dir>` | **只**装进一个目录（单宿主 / 兼容旧用法） |
70
+ | `add … --host claude-code` | 兼容旧用法：单宿主默认 dest |
71
+ | `update -g` | 从 canonical 里的 receipt 重装 |
72
+ | `agents` · `paths` · `doctor [--repair]` | 智能体矩阵 / 路径 / 修复断链 |
102
73
 
103
- 包名：[`@topmindspace/topmind-skills`](https://www.npmjs.com/package/@topmindspace/topmind-skills)
104
- Org：`topmindspace` · 访问级别：`public` · 版本真源：`topmind-pack.json`（须与 `package.json` `version` 一致）
74
+ ---
105
75
 
106
- ```bash
107
- # 1) 同步版本（package.json + topmind-pack.json + 各 SKILL.md）
108
- npm test
76
+ ## Installers
109
77
 
110
- # 2) 发布（需 npmjs 登录；scoped public 包）
111
- npm publish --access public
112
- # package.json 已配置 publishConfig.access=public，直接 npm publish 亦可
78
+ ### A. npm / Pack-aware（推荐）
113
79
 
114
- # 3) 验证
115
- npm view @topmindspace/topmind-skills
116
- npx @topmindspace/topmind-skills --help
117
- ```
80
+ 装齐 skill 目录 + `shared/` + `topmind-pack.json`，保证 `../shared/*.md` 渐进披露可用。
118
81
 
119
- ### GitHub 更新后 npm 会自动更新吗？
82
+ ```bash
83
+ # 矩阵：canonical .agents + 已检测智能体（全局）
84
+ npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g
120
85
 
121
- **不会。** GitHub 仓库 push / skills 内容变更 **不会** 自动发布到 npmjs。
86
+ # 只喂给部分智能体
87
+ npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g -a claude-code -a mimocode
122
88
 
123
- | 渠道 | 触发 | 是否自动 |
124
- |------|------|----------|
125
- | GitHub 仓库 / skills.sh | `git push` | 是（直连索引） |
126
- | GitHub Release | push tag `v*` | 是（CI 打包 Release） |
127
- | npm `@topmindspace/topmind-skills` | `npm publish` | **否**（需手动，或依赖下述 tag 自动发布） |
89
+ # 项目级
90
+ npx @topmindspace/topmind-skills add topmindspace/topmind-skills -p
128
91
 
129
- 若要在打 tag 发 Release 时 **自动同步 npm**：
92
+ # 单目录（旧 --dest 仍可用）
93
+ npx @topmindspace/topmind-skills add topmindspace/topmind-skills --dest ~/.claude/skills
130
94
 
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
95
+ # 升级（读 receipt）
96
+ npx @topmindspace/topmind-skills update -g
134
97
 
135
- 没有 `NPM_TOKEN` 时，npm 发布步骤会跳过，不影响 GitHub Release。
98
+ # 查看
99
+ npx @topmindspace/topmind-skills agents
100
+ npx @topmindspace/topmind-skills paths -g
101
+ npx @topmindspace/topmind-skills doctor --repair
136
102
 
137
- ---
103
+ # 本地开发：symlink 热更新（单目录）
104
+ node bin/install-skills.mjs add . --mode symlink --dest ~/.claude/skills
138
105
 
139
- ## Two installers (pick one)
106
+ # Release zip
107
+ node bin/install-skills.mjs add release:latest -g
108
+ ```
140
109
 
141
- > 优先用上文 **§0 Via npm**（`npx @topmindspace/topmind-skills …`）——它就是 B 的 pack-aware 安装器，且自动带上 `shared/`。下面 A/B 说明底层两种安装路径。
110
+ 私有仓：`export GH_TOKEN=…`（或 `GITHUB_TOKEN`）后再 `add`。
142
111
 
143
- ### A. Community CLI — `npx skills`（和开源 skills 生态一致）
112
+ ### B. Community CLI — `npx skills`
144
113
 
145
- 已验证：本仓库可被直接发现 pack 内全部 skill（含可选 weread / x / ledger）。
114
+ 适用于认 Agent Skills 目录布局的 host。
146
115
 
147
116
  ```bash
148
- # 安装到用户全局（$HOME/.claude/skills 等，按 agent 探测）
149
117
  npx skills add topmindspace/topmind-skills -g -y
150
-
151
- # 只装部分
152
118
  npx skills add topmindspace/topmind-skills -g -y -s topmind -s topmind-capture
153
-
154
- # 升级
155
119
  npx skills update -g -y
156
-
157
- # 列出仓库里有什么（不装）
158
120
  npx skills add topmindspace/topmind-skills -l
159
121
  ```
160
122
 
161
- 适用：Claude Code / Cursor / Codex / OpenCode 等认 Agent Skills 目录布局的 host。
123
+ **注意：社区 CLI 不会装 `shared/`。** topmind skill 有 `../shared/*.md` 链接，缺了会打不开子文档。装完后请再跑一次 pack-aware（或手动拷 `shared/`）：
162
124
 
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 / …)
125
+ ```bash
126
+ npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g
127
+ # 或
128
+ cp -R /path/to/topmind-skills/shared ~/.agents/skills/shared
170
129
  ```
171
130
 
172
- 末尾的 `Failed to install 9` **只针对 PromptScript**：该 host **不支持 global 安装**，不是 topmind 包损坏。可忽略，或不要装 PromptScript。
131
+ 日志末尾若出现 `Failed to install 9` 且指向 **PromptScript**，是该 host 不支持 global 安装，可忽略；topmind 本身已装上。
173
132
 
174
- 验收：
133
+ ---
175
134
 
176
- ```bash
177
- ls $HOME/.agents/skills/topmind/SKILL.md
178
- ls $HOME/.claude/skills/topmind # 常为 symlink → $HOME/.agents/skills/topmind
179
- ```
135
+ ## Source / options
180
136
 
181
- #### 社区 CLI 不会装 `shared/`（重要）
137
+ | Source | 含义 |
138
+ |--------|------|
139
+ | `topmindspace/topmind-skills` | GitHub `owner/repo`，默认分支，pack 在仓根 |
140
+ | `topmindspace/topmind-skills@v*` | 指定 ref / tag |
141
+ | `https://github.com/topmindspace/topmind-skills.git` | 任意 git URL |
142
+ | `./` / 绝对路径 | 本地 pack 根 |
143
+ | `release:latest` | GitHub Release 里的 `topmind-skills-*.zip` |
182
144
 
183
- 社区 CLI 只复制含 `SKILL.md` 的目录。topmind skill 内有 `../shared/*.md` 渐进披露链接，**缺 `shared/` 时子文档打不开**。
145
+ | Option | 含义 |
146
+ |--------|------|
147
+ | `-g` / `--global` | **全局 scope**（canonical `~/.agents/skills`）— 与 `npx skills -g` 同义 |
148
+ | `-p` / `--project` | 项目 scope（canonical `./.agents/skills`） |
149
+ | `-a` / `--agent <ids>` | 目标智能体（可多个；`'*'` 全部） |
150
+ | `--copy` | 私有目录复制而非软链 |
151
+ | `--dest <dir>` | 只装进这个 skills 根（绕过矩阵） |
152
+ | `--host <name>` | 兼容旧用法：单宿主默认 dest |
153
+ | `--mode copy\|symlink` | 单目录安装模式（默认 copy） |
154
+ | `--skill <id>` | 只装列出的 skill id |
155
+ | `--locale en-US` | locale overlay（当前未提供 overlay，回退中文正文） |
156
+ | `-n` / `--dry-run` | 只打印计划 |
157
+ | `--force` | symlink 模式下替换非软链目标 |
158
+
159
+ ### Agents
160
+
161
+ | id | 项目路径 | 全局路径 | 类型 |
162
+ |----|----------|----------|------|
163
+ | `universal` | `.agents/skills` | `~/.agents/skills` | canonical |
164
+ | `claude-code` | `.claude/skills` | `~/.claude/skills` | private |
165
+ | `mimocode` | `.mimocode/skills` | `~/.config/mimocode/skills` | private |
166
+ | `codex` | `.agents/skills` | `~/.codex/skills` | 项目 universal / 全局 private |
167
+ | `cursor` | `.agents/skills` | `~/.cursor/skills` | 同上 |
168
+ | `gemini-cli` | `.agents/skills` | `~/.gemini/skills` | 同上 |
169
+ | `opencode` | `.agents/skills` | `~/.config/opencode/skills` | 同上 |
170
+ | `hermes` | `.hermes/skills` | `~/.hermes/skills` | private |
171
+ | `github-copilot` | `.agents/skills` | `~/.copilot/skills` | 项目 universal / 全局 private |
172
+
173
+ 无 skill 系统的 host：把 `topmind/SKILL.md` 当 system 片段粘贴，`shared/` 按链接手动附上。
184
174
 
185
- 这是开放标准「单 skill 目录」与 topmind **pack 级 shared** 的已知差异。加载契约见 [`shared/host-loading.md`](./shared/host-loading.md)。
175
+ ---
176
+
177
+ ## Update
186
178
 
187
- 装完社区 CLI 后**务必**再跑 pack-aware（或手动拷 shared）：
179
+ 安装后 **canonical** 会写入 `.topmind-skills-install.json`（记录 `source` / `scope` / `agents` / `version`）：
188
180
 
189
181
  ```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
198
- cp -R /path/to/topmind-skills/shared $HOME/.agents/skills/shared
182
+ npx @topmindspace/topmind-skills update -g
183
+ # 或
184
+ node bin/install-skills.mjs update -g
185
+ # 社区 CLI
186
+ npx skills update -g -y
199
187
  ```
200
188
 
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/`。
189
+ ---
213
190
 
214
- ### Zip 加载报 `SKILL.md not found`？
191
+ ## Zip 加载报 `SKILL.md not found`？
215
192
 
216
- topmind Release 包是 **多 skill 组合包**，不是单目录 skill：
193
+ Release 包是 **多 skill 组合包**：
217
194
 
218
195
  ```text
219
196
  topmind-skills-<ver>.zip
220
197
  └── topmind-skills-<ver>/
221
198
  ├── SKILL.md ← 根入口 = router
222
199
  ├── topmind/SKILL.md ← 推荐日常入口
223
- ├── topmind-capture/…
200
+ ├── topmind-*/
224
201
  └── shared/
225
202
  ```
226
203
 
227
204
  | Host 行为 | 正确处理 |
228
205
  |-----------|----------|
229
- | 解压 zip 后在根找 `SKILL.md` | 用包内根 `SKILL.md`（router） |
230
- | 扫描 `*/SKILL.md` 多 skill | 装全部 `topmind*` 目录 + `shared/` |
231
- | 社区 `npx skills add` | 从 GitHub 仓根装 skill 目录（不依赖 zip 根） |
206
+ | 在 zip 根找 `SKILL.md` | 用包内根 `SKILL.md`（router） |
207
+ | 扫描 `*/SKILL.md` | 装全部 `topmind*` 目录 + `shared/` |
208
+ | `npx skills add` | 从 GitHub 仓根装（不依赖 zip 根） |
232
209
 
233
- `skills.md` 是 **包索引**（人类可读），不是 Agent Skills 标准的 `SKILL.md` 替代名——两者并存，不要把 `skills.md` 改成唯一入口。
210
+ `skills.md` 是包索引，不是 `SKILL.md` 的替代名。
234
211
 
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
- 根脚本别名：
212
+ ---
266
213
 
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
- ```
214
+ ## 发布（GitHub Release + npm）
272
215
 
273
- 或直接用 npm 包 CLI（无需 clone）：
216
+ 版本真源：`topmind-pack.json`（须与 `package.json` `version`、各 `SKILL.md` / `evals` 一致）。
274
217
 
275
218
  ```bash
276
- npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g
277
- ```
278
-
279
- 私有仓：
219
+ # 1) 同步 bump 版本后校验
220
+ npm test
221
+ npm run pack # 可选：本地 dist 产物
280
222
 
281
- ```bash
282
- export GH_TOKEN=... # 或 GITHUB_TOKEN
283
- node bin/install-skills.mjs add topmindspace/topmind-skills -g
223
+ # 2) 提交并打 tag（推荐发版方式）
224
+ git add . && git commit -m "chore: topmind-skills x.y.z"
225
+ git tag vX.Y.Z
226
+ git push origin main vX.Y.Z
284
227
  ```
285
228
 
286
- ---
287
-
288
- ## Source 写法
229
+ push tag `v*` 后 CI 自动：
289
230
 
290
- | Source | 含义 |
291
- |--------|------|
292
- | `topmindspace/topmind-skills` | GitHub `owner/repo`，默认分支，pack 在仓根 |
293
- | `topmindspace/topmind-skills@v*` | 指定 ref / tag（版本见 `topmind-pack.json`） |
294
- | `https://github.com/topmindspace/topmind-skills.git` | 任意 git URL |
295
- | `./skills` / 绝对路径 | 本地 pack 根（含 `topmind-pack.json` 或 `*/SKILL.md`） |
296
- | `release:latest` | GitHub Release 里的 `topmind-skills-*.zip` |
297
-
298
- | Option | 含义 |
299
- |--------|------|
300
- | `--path <subdir>` | 仓库内 pack 子目录（默认 `.` 仓根） |
301
- | `--dest <dir>` | 安装目标 = host 的 skills 根 |
302
- | `-g` / `--global` | dest → `$HOME/.claude/skills` |
303
- | `--host codex` 等 | 换默认 dest |
304
- | `--mode symlink` | 仅本地源；开发时热更新 |
305
- | `--skill topmind` | 只装列出的 skill id（可重复） |
306
- | `--locale en-US` | 安装 locale overlay（回退到 `topmind_LOCALE` 环境变量）。**当前未随包提供任何 overlay**——技能正文以 zh-CN 为准，`--locale` 会回退到中文正文，不是英文版技能。 |
231
+ 1. 测试 + 打包
232
+ 2. 创建 GitHub Release（附 zip / tar.gz / manifest / SHA256SUMS / latest.json）
233
+ 3. `npm publish` → [`@topmindspace/topmind-skills`](https://www.npmjs.com/package/@topmindspace/topmind-skills)（需仓库 Secret `NPM_TOKEN`，Automation token）
234
+ 4. **只保留最近 2 个 GitHub Release**，更旧的 Release 与 tag 会被删除
307
235
 
308
- ---
309
-
310
- ## Host destinations
311
-
312
- | Host | 典型 dest | 写法 |
313
- |------|-----------|------|
314
- | Claude Code | `$HOME/.claude/skills` 或项目 `.claude/skills` | `-g` 或 `--dest ./.claude/skills` |
315
- | Codex | `$HOME/.codex/skills` | `--host codex` |
316
- | Hermes | `$HOME/.hermes/skills` | `--host hermes` |
317
- | OpenCode | 项目 skills 路径 / config `skills.paths` | `--host opencode` 或见 `integrations/opencode/` |
318
-
319
- `install-targets/*.json` 描述各 host 契约（无硬编码本机绝对路径）。
320
-
321
- ---
322
-
323
- ## Update 原理
324
-
325
- 安装后在 dest 写入：
326
-
327
- ```text
328
- {dest}/.topmind-skills-install.json
329
- ```
236
+ | 渠道 | 触发 | 自动 |
237
+ |------|------|------|
238
+ | GitHub 仓库 / skills.sh | `git push` | 是（直连索引） |
239
+ | GitHub Release | tag `v*` | 是 |
240
+ | npm | tag `v*`（有 `NPM_TOKEN`） | 是 |
330
241
 
331
- 里面记录了 `source` / `path` / `version`。之后只需：
242
+ 手动兜底（无 CI 时）：
332
243
 
333
244
  ```bash
334
- node bin/install-skills.mjs update --dest <同一 dest>
245
+ npm publish --access public
335
246
  ```
336
247
 
337
- 就会按原 source 再拉一遍并覆盖（升级）。
248
+ ### skills.sh
338
249
 
339
- 社区 CLI 对应：
250
+ 公开 GitHub 仓即可被 `npx skills` / [skills.sh](https://skills.sh/topmindspace/topmind-skills) 索引，无需额外注册：
340
251
 
341
252
  ```bash
342
- npx skills update -g -y
343
- ```
344
-
345
- ---
346
-
347
- ## 装完长什么样
348
-
349
- ```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
253
+ npx skills add topmindspace/topmind-skills -g -y
254
+ npx skills add topmindspace/topmind-skills -l
358
255
  ```
359
256
 
360
- 在 host 里调用 **`topmind`**。子 skill 是模块，不是并列产品入口。
361
-
362
- ---
363
-
364
- ## OpenCode（可选）
365
-
366
- 示例：`integrations/opencode/opencode.example.json` — 用 `skills.paths` 指向本仓根或已安装目录。
367
-
368
257
  ---
369
258
 
370
259
  ## Security
371
260
 
372
261
  - Skills 是 Markdown 指令；不信任的 fork 先审再装。
373
262
  - API Key 不要写进 skill 文件。
374
- - 安装器只写 `--dest`，不改 engine 仓库（除非 dest 故意指过去）。
263
+ - 安装器只写 canonical 与所选智能体技能根，不改其他目录。
264
+ - 断链（第三方卸载残留）用 `doctor --repair` 修复，不要手删整棵技能树。
package/README.en.md CHANGED
@@ -2,27 +2,33 @@
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
- # 1) npm (recommended · pack-aware · includes shared/)
8
+ # 1) npm (recommended · pack-aware · includes shared/ · canonical .agents + agents)
9
9
  npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g
10
+ # subset of agents
11
+ npx @topmindspace/topmind-skills add topmindspace/topmind-skills -g -a claude-code -a mimocode
10
12
  # upgrade
11
13
  npx @topmindspace/topmind-skills update -g
12
14
 
13
- # 2) Community CLI (fast try; may omit shared/)
15
+ # 2) Community CLI (fast try; omits shared/ — see INSTALL.md)
14
16
  npx skills add topmindspace/topmind-skills -g -y
15
17
 
16
18
  # 3) Pack-aware installer (from a source checkout)
17
19
  npm run add -- topmindspace/topmind-skills -g
18
- npm run update -- --dest $HOME/.claude/skills
20
+ npm run update -- -g
19
21
 
20
22
  # 4) From GitHub Release (pinned version / offline)
21
23
  node bin/install-skills.mjs add release:latest -g
22
- # or after downloading topmind-skills-<ver>.zip:
23
- # node bin/install-skills.mjs add ./unpacked --dest $HOME/.claude/skills
24
+
25
+ # Inspect matrix / repair broken roots
26
+ node bin/install-skills.mjs agents
27
+ node bin/install-skills.mjs doctor --repair
24
28
  ```
25
29
 
30
+ Install model: **one canonical body under `.agents/skills`** plus relative symlinks into private host roots (Claude Code, MiMoCode, …) — same as [`npx skills`](https://github.com/vercel-labs/skills) and `@topmindspace/tms-skills`. See [INSTALL.md](./INSTALL.md).
31
+
26
32
  **Version and manifest truth:** [`topmind-pack.json`](./topmind-pack.json) (`npm run versions`).
27
33
  Each `SKILL.md` `version` **must** equal the pack version.
28
34
 
@@ -93,7 +99,7 @@ degradation: ../shared/capability-degradation.md
93
99
  ---
94
100
  ```
95
101
 
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).
102
+ Enforced by `tests/package-manifest.test.mjs`. One pack JSON ([`topmind-pack.json`](./topmind-pack.json)); no per-skill second manifest.
97
103
 
98
104
  ---
99
105
 
@@ -136,7 +142,7 @@ Do not hardcode absolute paths — infer `workspace_root` from the host or ask.
136
142
  5. **参考资料定位**
137
143
  6. **大类命名稳定**（rename via migration）
138
144
 
139
- Full rules: [`../PROJECT-MODEL.md`](../PROJECT-MODEL.md) §3.
145
+ Full rules: [`shared/project-model-brief.md`](./shared/project-model-brief.md).
140
146
 
141
147
  ---
142
148
 
@@ -160,4 +166,4 @@ Full rules: [`../PROJECT-MODEL.md`](../PROJECT-MODEL.md) §3.
160
166
  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
167
  Prefer the pack-aware installer so `shared/` and `topmind-pack.json` stay intact — see [`INSTALL.md`](./INSTALL.md).
162
168
 
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).
169
+ 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).