@topmindspace/topmind-writing-skills 0.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TopMindspace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,124 @@
+# topmind-writing-skills
+
+**[中文](./README.md)** | English
+
+> Language note: **Chinese is the default** (`README.md`). This file is the full English parallel.
+
+[![Release](https://img.shields.io/github/v/release/topmindspace/topmind-writing-skills?style=flat-square&color=blue)](https://github.com/topmindspace/topmind-writing-skills/releases)
+[![npm](https://img.shields.io/npm/v/@topmindspace/topmind-writing-skills?style=flat-square)](https://www.npmjs.com/package/@topmindspace/topmind-writing-skills)
+[![CI](https://img.shields.io/github/actions/workflow/status/topmindspace/topmind-writing-skills/ci.yml?style=flat-square&label=CI)](https://github.com/topmindspace/topmind-writing-skills/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](LICENSE)
+
+**TopMindSpace writing-skills collection** — WeChat articles, X long-form posts, short-form briefs, cover art: four skills, one repo.
+
+<p align="center">
+  <img src="docs/assets/writing-cover-white.png" alt="topmind-writing-skills · writing skills collection" width="960" />
+</p>
+
+> The formal business presentation skill now lives on its own: [`topmind-presentation`](https://github.com/topmindspace/topmind-presentation) (repo `topmind-presentation`; the repo is the skill — clone and copy the root into your skills directory).
+
+### topmind-wechat-post · WeChat article authoring
+
+Full lifecycle for WeChat articles: delivery package, review & rewrite, three quality gates (facts / logic / de-AI-flavor), WeChat inline typography (images must be embedded), publish checklist and status sync. Python stdlib only — zero dependencies.
+
+```bash
+npx @topmindspace/topmind-writing-skills install topmind-wechat-post
+```
+
+### topmind-x-article · One-click X long-form publishing
+
+Markdown draft → paste-ready plain text (`md2x.py` adapts to the X Article editor: images → `[图N]`, tables → "item: value" lists) + cover art + publish checklist. Publishing is done by hand-pasting; fetch the text back for verification after posting.
+
+```bash
+npx @topmindspace/topmind-writing-skills install topmind-x-article
+```
+
+### topmind-briefs · Short-form briefs
+
+Short-form briefs for WeChat + X: one topic, one chart (data rankings / paper one-liners / product alerts / mechanism explainers). One X post or short thread, WeChat ~300–800 words, 1 key visual. One-click-copy HTML for both, draft only — never auto-post.
+
+```bash
+npx @topmindspace/topmind-writing-skills install topmind-briefs
+```
+
+### topmind-cover · Cover art generation
+
+Shared cover art for X long-form and WeChat: striking, eye-catching, theme-focused. **Pick a style → check the example → compose the prompt from the recipe**, then one-click crop to both platform sizes with `crop-cover.py` (X 1200×675, WeChat 900×383). 11-style index and recipes: [`references/cover-styles.md`](./topmind-cover/references/cover-styles.md).
+
+```bash
+npx @topmindspace/topmind-writing-skills install topmind-cover
+```
+
+<p align="center">
+  <img src="https://github.com/topmindspace/topmind-writing-skills/raw/main/topmind-cover/assets/examples/overview.png" alt="topmind-cover · 11 cover-style overview" width="960" />
+</p>
+
+> Let ideas fly — make good thinking visible.
+
+> **Rename note**: this repo was renamed from `tms-skills` to `topmind-writing-skills`;
+> the npm package is `@topmindspace/topmind-writing-skills` and the old package is no longer updated.
+> Also do not install the old package's `^2` (2.0.0–2.1.1 deprecated).
+
+## Skills
+
+| Skill | Version | What it does |
+|-------|---------|--------------|
+| [`topmind-wechat-post`](./topmind-wechat-post/) | **0.2.0** | WeChat article lifecycle: package, review, 3 quality gates, inline typography & publish checklist |
+| [`topmind-x-article`](./topmind-x-article/) | **0.4.0** | X long-form one-click publish: Markdown → one-click-copy HTML (images/prompt copy, click-to-zoom images) / plain-text fallback + cover + checklist |
+| [`topmind-cover`](./topmind-cover/) | **0.3.0** | Cover art for X / WeChat (X master 1500×600 / 5:2): striking, theme-focused; 11-style cover style library + 26 example images (incl. 3 alt samples) + 1 style overview |
+| [`topmind-briefs`](./topmind-briefs/) | **0.2.1** | Short-form briefs (WeChat + X): one topic, one chart; data rankings / paper one-liners / product alerts / mechanism explainers; one-click-copy HTML for both |
+
+Installer [`@topmindspace/topmind-writing-skills`](https://www.npmjs.com/package/@topmindspace/topmind-writing-skills) is **0.7.0** (whole-repo same-tag releases).
+
+## Install
+
+**npm = pinned snapshot**; **GitHub = track repo HEAD**.
+
+```bash
+npx @topmindspace/topmind-writing-skills list
+npx @topmindspace/topmind-writing-skills install topmind-briefs
+npx @topmindspace/topmind-writing-skills install topmind-briefs --to ./.claude/skills
+npx @topmindspace/topmind-writing-skills@0.7.1 install topmind-briefs   # pin
+npx @topmindspace/topmind-writing-skills uninstall topmind-briefs --to ./.claude/skills
+```
+
+```bash
+# track HEAD
+npx github:topmindspace/topmind-writing-skills install topmind-briefs
+```
+
+Default probe order: `./.agents` → `./.claude` → `./.cursor` → `./.codex` → `./.mimocode`, then user-level `~/.claude`, etc. Or pass `--to`. When `--to` is omitted, the install summary explicitly prints the auto-detected target directory. Do not `npm install topmind-briefs` (skill id is not a standalone package).
+
+`install` details: if a same-named skill already exists, the installed version is reported and overwriting is refused — pass `--force` to replace (or `uninstall` first). On success, a three-line summary is printed: where it was installed / installed skill version and installer version / next steps.
+
+## Repo layout
+
+```
+topmind-writing-skills/
+├─ topmind-briefs/                    # skill (SKILL.md + assets + references + scripts)
+├─ topmind-cover/                     # skill
+├─ topmind-wechat-post/               # skill
+├─ topmind-x-article/                 # skill
+├─ bin/topmind-writing-skills.js      # CLI: list / install / uninstall
+├─ docs/                              # publishing guide · CI notes (history archived in docs/archive)
+├─ scripts/                           # repo gates / privacy scan
+├─ package.json                       # @topmindspace/topmind-writing-skills
+└─ LICENSE · CHANGELOG.md · README.md · README.en.md
+```
+
+## Release & CI
+
+| Action | GitHub | npm |
+|--------|:------:|:---:|
+| push main | live | **unchanged** |
+| tag `vX.Y.Z` | Release + zip | **auto publish** |
+
+```bash
+npm run check && npm run audit && npm run privacy
+```
+
+See [docs/PUBLISHING.md](./docs/PUBLISHING.md) · [docs/ci.md](./docs/ci.md).
+
+## License
+
+MIT © TopMindspace — [LICENSE](./LICENSE)

package/README.md

@@ -0,0 +1,124 @@
+# topmind-writing-skills
+
+[English](./README.en.md) | 中文
+
+[![Release](https://img.shields.io/github/v/release/topmindspace/topmind-writing-skills?style=flat-square&color=blue)](https://github.com/topmindspace/topmind-writing-skills/releases)
+[![npm](https://img.shields.io/npm/v/@topmindspace/topmind-writing-skills?style=flat-square)](https://www.npmjs.com/package/@topmindspace/topmind-writing-skills)
+[![CI](https://img.shields.io/github/actions/workflow/status/topmindspace/topmind-writing-skills/ci.yml?style=flat-square&label=CI)](https://github.com/topmindspace/topmind-writing-skills/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](LICENSE)
+
+**TopMindSpace 写作技能合集** —— 公众号文章、X 长文、干货短文、封面配图：四个技能，一个仓库。
+
+<p align="center">
+  <img src="docs/assets/writing-cover-white.png" alt="topmind-writing-skills · 写作技能合集" width="960" />
+</p>
+
+> 正式商务演示技能已独立出去：[`topmind-presentation`](https://github.com/topmindspace/topmind-presentation)（仓库 `topmind-presentation`，仓库即技能，clone 后复制根目录到技能目录即可）。
+
+### topmind-wechat-post · 公众号创作
+
+公众号文章全生命周期：交付包、审校改写、质量三关（事实 / 逻辑 / 去 AI 味）、微信内联排版（图片必内嵌）、发布清单与状态同步。脚本纯 Python 标准库，零依赖。
+
+```bash
+npx @topmindspace/topmind-writing-skills install topmind-wechat-post
+```
+
+### topmind-x-article · X 长文一键发布
+
+Markdown 原稿 → 可直接粘贴的纯文本（`md2x.py` 按 X Article 编辑器支持转制：图片→`[图N]`、表格→"项：值"列表）+ 封面图 + 发布清单。发布走人工粘贴，发布后抓回核对。
+
+```bash
+npx @topmindspace/topmind-writing-skills install topmind-x-article
+```
+
+### topmind-briefs · 干货短文
+
+公众号 + X 双平台干货短文：一件事讲透（数据榜单 / 论文一句话解读 / 新品速递 / 机制讲解），X 一帖或短 thread、公众号约 300–800 字，1 张核心图。双版一键复制 HTML，只起草不代发。
+
+```bash
+npx @topmindspace/topmind-writing-skills install topmind-briefs
+```
+
+### topmind-cover · 封面配图生成
+
+X 长文与公众号共用的封面图：震撼、醒目、主题突出。**选风格 → 看示例 → 按配方组 prompt** 三步出图，`crop-cover.py` 一键裁出双平台尺寸（X 1200×675、公众号 900×383）。11 种风格索引与配方见 [`references/cover-styles.md`](./topmind-cover/references/cover-styles.md)。
+
+```bash
+npx @topmindspace/topmind-writing-skills install topmind-cover
+```
+
+<p align="center">
+  <img src="https://github.com/topmindspace/topmind-writing-skills/raw/main/topmind-cover/assets/examples/overview.png" alt="topmind-cover · 11 封面风格总览" width="960" />
+</p>
+
+> 让 idea 飞，好想法被看见。
+
+> **改名说明**：本仓由 `tms-skills` 改名为 `topmind-writing-skills`，
+> npm 包为 `@topmindspace/topmind-writing-skills`，旧包不再更新。
+> 也不要安装旧包的 `^2`（2.0.0–2.1.1 已弃用）。
+
+## 技能一览
+
+| 技能 | 版本 | 做什么 |
+|------|------|--------|
+| [`topmind-wechat-post`](./topmind-wechat-post/) | **0.2.0** | 公众号文章全生命周期：交付包、审校改写、质量三关、微信内联排版与发布清单 |
+| [`topmind-x-article`](./topmind-x-article/) | **0.4.0** | X 长文一键发布：Markdown 原稿 → 一键复制 HTML（含配图/提示词复制、图片点击放大）/ 纯文本兜底 + 封面图 + 发布清单 |
+| [`topmind-cover`](./topmind-cover/) | **0.3.0** | 文章封面配图（X / 公众号共用，X 主尺寸 1500×600 / 5:2）：震撼醒目主题突出；11 风格封面风格库 + 26 张示例图（含 3 张 alt 样张） + 1 张风格总览图 |
+| [`topmind-briefs`](./topmind-briefs/) | **0.2.1** | 干货短文（公众号 + X 双平台）：一件事讲透，数据榜单/论文解读/新品速递；双版一键复制 HTML |
+
+安装器 [`@topmindspace/topmind-writing-skills`](https://www.npmjs.com/package/@topmindspace/topmind-writing-skills) 为 **0.7.0**（整仓同 tag 发版）。
+
+> SKILL.md frontmatter 除标准 `name`/`description` 外，本仓库扩展了 `action_category` / `triggers` / `triggers_cn` / `updated` 字段供安装器与路由使用。
+
+## 安装
+
+**npm = 钉版本快照**；**GitHub = 跟仓库 HEAD**。
+
+```bash
+npx @topmindspace/topmind-writing-skills list
+npx @topmindspace/topmind-writing-skills install topmind-briefs
+npx @topmindspace/topmind-writing-skills install topmind-briefs --to ./.claude/skills
+npx @topmindspace/topmind-writing-skills@0.7.1 install topmind-briefs   # 钉版本
+npx @topmindspace/topmind-writing-skills uninstall topmind-briefs --to ./.claude/skills
+```
+
+```bash
+# 跟 HEAD
+npx github:topmindspace/topmind-writing-skills install topmind-briefs
+```
+
+默认探测：`./.agents` → `./.claude` → `./.cursor` → `./.codex` → `./.mimocode`，再用户级 `~/.claude` 等；也可用 `--to`。未给 `--to` 时安装摘要会明确打印探测到的目标目录。不要 `npm install topmind-briefs`（技能 id 不是独立包）。
+
+`install` 细节：若同名技能已存在，会报出已装版本并拒绝覆盖，需加 `--force` 才替换（或先 `uninstall` 再装）。安装成功后打印三行摘要：装到哪里 / 装的技能版本与安装器版本 / 下一步。
+
+## 仓库结构
+
+```
+topmind-writing-skills/
+├─ topmind-briefs/               # 技能（SKILL.md + assets + references + scripts）
+├─ topmind-cover/                # 技能
+├─ topmind-wechat-post/          # 技能
+├─ topmind-x-article/            # 技能
+├─ bin/topmind-writing-skills.js # CLI：list / install / uninstall
+├─ docs/                         # 发布规范 · CI 说明（历史审计归档在 docs/archive）
+├─ scripts/                      # 仓库级门禁 / 隐私扫描
+├─ package.json                  # @topmindspace/topmind-writing-skills
+└─ LICENSE · CHANGELOG.md · README.md · README.en.md
+```
+
+## 发布与 CI
+
+| 动作 | GitHub | npm |
+|------|:------:|:---:|
+| push main | 立即可见 | **不变** |
+| tag `vX.Y.Z` | Release + zip | **自动 publish** |
+
+```bash
+npm run check && npm run audit && npm run privacy
+```
+
+详见 [docs/PUBLISHING.md](./docs/PUBLISHING.md) · [docs/ci.md](./docs/ci.md)。
+
+## 许可证
+
+MIT © TopMindspace — [LICENSE](./LICENSE)

package/bin/topmind-writing-skills.js

@@ -0,0 +1,388 @@
+#!/usr/bin/env node
+/**
+ * topmind-writing-skills — TopMindspace agent skills installer
+ *
+ * Recommended channel (when published): npm @topmindspace/topmind-writing-skills
+ * GitHub npx remains available for HEAD / offline clone.
+ *
+ * Usage:
+ *   npx @topmindspace/topmind-writing-skills list
+ *   npx @topmindspace/topmind-writing-skills install topmind-briefs
+ *   npx @topmindspace/topmind-writing-skills install topmind-briefs --to ./skills-out
+ *   npx @topmindspace/topmind-writing-skills install topmind-briefs --force
+ *   npx @topmindspace/topmind-writing-skills uninstall topmind-briefs --to ./skills-out
+ *   npx github:topmindspace/topmind-writing-skills install topmind-briefs   # follow repo HEAD
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+// Skills live at repo root (one directory per skill with SKILL.md).
+const INFRA_DIRS = new Set(['bin', 'docs', 'scripts', 'node_modules', 'dist', 'release-assets']);
+const SKILL_ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+function die(msg, code = 1) {
+  console.error(msg);
+  process.exit(code);
+}
+
+function skillDir(skillId) {
+  return path.join(ROOT, skillId);
+}
+
+function assertSkillId(skillId) {
+  if (!skillId || typeof skillId !== 'string') {
+    die('Missing skill id.\n\n' + usageText());
+  }
+  if (
+    skillId.includes('..') ||
+    skillId.includes('/') ||
+    skillId.includes('\\') ||
+    path.isAbsolute(skillId) ||
+    !SKILL_ID_RE.test(skillId)
+  ) {
+    die(
+      `Invalid skill id: ${JSON.stringify(skillId)}\n` +
+        'Skill ids must match ^[a-z0-9]+(?:-[a-z0-9]+)*$ (no paths, dots, or slashes).'
+    );
+  }
+}
+
+function listSkillIds() {
+  return fs
+    .readdirSync(ROOT, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && !INFRA_DIRS.has(d.name) && !d.name.startsWith('.'))
+    .filter((d) => fs.existsSync(path.join(ROOT, d.name, 'SKILL.md')))
+    .map((d) => d.name)
+    .sort();
+}
+
+function readSkillMeta(skillId) {
+  const skillPath = skillDir(skillId);
+  const skillMd = path.join(skillPath, 'SKILL.md');
+  if (!fs.existsSync(skillMd)) return { id: skillId, description: '' };
+  const text = fs.readFileSync(skillMd, 'utf8');
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return { id: skillId, description: '' };
+  const fm = m[1];
+  let desc = '';
+  // 块标量：description: >- / > / | / |- 后跟缩进行
+  const block = fm.match(/^description:\s*[>|][-+]?\s*$/m);
+  if (block) {
+    const lines = [];
+    // slice 起点是 description 行尾，split 后首元素恒为空，直接丢掉
+    const rest = fm.slice(block.index + block[0].length).split(/\r?\n/).slice(1);
+    for (const ln of rest) {
+      if (/^[ \t]+\S/.test(ln)) lines.push(ln.trim()); // 缩进的内容行
+      else break; // 空行或顶格行 → 块结束
+    }
+    const folded = /^description:\s*>/.test(block[0]);
+    desc = folded ? lines.join(' ') : lines.join('\n');
+  } else {
+    desc = ((fm.match(/^description:\s*"(.*)"\s*$/m) || fm.match(/^description:\s*(.+)\s*$/m) || [])[1] || '');
+  }
+  return { id: skillId, description: String(desc).slice(0, 120) };
+}
+
+/** 读技能目录下 SKILL.md frontmatter 的 version 字段（读不到返回 ''，调用方兜底）。 */
+function readSkillVersion(skillPath) {
+  try {
+    const p = path.join(skillPath, 'SKILL.md');
+    if (!fs.existsSync(p)) return '';
+    const text = fs.readFileSync(p, 'utf8');
+    const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!m) return '';
+    const v = m[1].match(/^version:\s*(.+?)\s*$/m);
+    return v ? v[1] : '';
+  } catch {
+    return '';
+  }
+}
+
+function installerVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+    return pkg.version || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+function resolveDefaultTarget() {
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  const candidates = [
+    path.join(process.cwd(), '.agents', 'skills'),
+    path.join(process.cwd(), '.claude', 'skills'),
+    path.join(process.cwd(), '.cursor', 'skills'),
+    path.join(process.cwd(), '.codex', 'skills'),
+    path.join(process.cwd(), '.mimocode', 'skills'),
+    path.join(home, '.claude', 'skills'),
+    path.join(home, '.agents', 'skills'),
+    path.join(home, '.cursor', 'skills'),
+    path.join(home, '.codex', 'skills'),
+  ];
+  for (const dir of candidates) {
+    if (dir && fs.existsSync(path.dirname(dir))) {
+      return dir;
+    }
+  }
+  return path.join(process.cwd(), '.agents', 'skills');
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '__pycache__') continue;
+      copyDir(s, d);
+    } else if (entry.isFile()) {
+      if (entry.name.endsWith('.pyc')) continue;
+      fs.copyFileSync(s, d);
+    } else {
+      console.warn(`warning: skipping non-regular file: ${s}`);
+    }
+  }
+}
+
+function normPath(p) {
+  const s = path.resolve(p);
+  return process.platform === 'win32' ? s.toLowerCase() : s;
+}
+
+/** realpath 能解析就解析（跟符号链接），失败回退 path.resolve。
+ *  dest 可能还不存在（install 流程）：往上找最深存在的祖先解析后再拼回。
+ *  否则 --to 经符号链接指向包内时，词法比对会被绕过（rmSync 会跟链接删掉源）。 */
+function realOrResolved(p) {
+  let cur = path.resolve(p);
+  const tail = [];
+  for (;;) {
+    try {
+      return path.join(fs.realpathSync(cur), ...tail);
+    } catch {
+      const parent = path.dirname(cur);
+      if (parent === cur) return path.join(cur, ...tail);
+      tail.unshift(path.basename(cur));
+      cur = parent;
+    }
+  }
+}
+
+/** 安装目标守卫（审计 严重-2）：
+ *  dest == 技能源目录  → --force 会先 rmSync 删掉源目录，再"成功"装出空目录（数据丢失 + 虚假成功）；
+ *  dest 在源目录内部  → copyDir 无限递归复制直至 ENAMETOOLONG，并留下垃圾目录树。
+ *  realpath 归一化后比对（dest === src，或 dest 以 src + 路径分隔符开头），
+ *  防止 --to 经符号链接指向包内绕过词法比对；
+ *  Windows 下额外做大小写归一。无论是否 --force，一律拒绝。
+ */
+function assertDestOutsideSource(src, dest) {
+  const absSrc = normPath(realOrResolved(src));
+  const absDest = normPath(realOrResolved(dest));
+  if (absDest === absSrc || absDest.startsWith(absSrc + path.sep)) {
+    die(
+      `Refusing to install into the skill's own directory tree.\n` +
+        `  skill source: ${absSrc}\n` +
+        `  destination:  ${absDest}\n` +
+        `Choose a --to directory outside the skill source ` +
+        `(installing into it would delete or recurse into the source).`
+    );
+  }
+}
+
+function install(skillId, targetRoot, { force = false, defaultTarget = false } = {}) {
+  assertSkillId(skillId);
+  const src = skillDir(skillId);
+  if (!fs.existsSync(path.join(src, 'SKILL.md'))) {
+    die(`Skill not found: ${skillId}\nAvailable: ${listSkillIds().join(', ') || '(none)'}`);
+  }
+  const dest = path.join(targetRoot, skillId);
+  assertDestOutsideSource(src, dest);
+  try {
+    fs.mkdirSync(targetRoot, { recursive: true });
+  } catch (e) {
+    die(
+      `Cannot create install directory: ${targetRoot}\n` +
+        `  reason: ${e.message}\n` +
+        'Choose a --to directory that can be created (not a file, not unwritable).'
+    );
+  }
+  if (fs.existsSync(dest)) {
+    if (!force) {
+      // 已装过：报出已装版本，要求 --force 才覆盖（不静默覆盖）。
+      const installedVer = readSkillVersion(dest) || 'unknown';
+      const packageVer = readSkillVersion(src) || 'unknown';
+      die(
+        `Already installed: ${dest}\n` +
+          `  installed version: ${installedVer} (this package ships ${packageVer})\n` +
+          'Refusing to overwrite. Pass --force (or -f) to replace, or remove it first:\n' +
+          `  topmind-writing-skills uninstall ${skillId} --to ${targetRoot}`
+      );
+    }
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+  copyDir(src, dest);
+  // 安装摘要三行：装到哪里 / 装了什么版本 / 下一步。
+  const toNote = defaultTarget ? '  (default, auto-detected — no --to given)' : '';
+  const skillVer = readSkillVersion(dest) || 'unknown';
+  console.log(`Installed ${skillId}`);
+  console.log(`  to:      ${dest}${toNote}`);
+  console.log(`  version: skill ${skillVer} (installer ${installerVersion()})`);
+  console.log(`  next:    ${nextStep(skillId, dest)}`);
+}
+
+function nextStep(skillId, dest) {
+  return 'restart your agent so it picks up the skill';
+}
+
+/** 列出目标根目录下已安装的技能（有 SKILL.md 的子目录）。 */
+function listInstalledIds(targetRoot) {
+  try {
+    return fs
+      .readdirSync(targetRoot, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && fs.existsSync(path.join(targetRoot, d.name, 'SKILL.md')))
+      .map((d) => d.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+function uninstall(skillId, targetRoot) {
+  assertSkillId(skillId);
+  const src = skillDir(skillId);
+  const dest = path.join(targetRoot, skillId);
+  // 守卫：--to 指到包内时，dest 会命中安装器自带的技能源目录 → 一律拒绝，
+  // 防止把仓库自身的技能目录删掉（同 install 的 assertDestOutsideSource）。
+  if (fs.existsSync(path.join(src, 'SKILL.md'))) {
+    assertDestOutsideSource(src, dest);
+  }
+  if (!fs.existsSync(dest)) {
+    const installed = listInstalledIds(targetRoot);
+    die(
+      `Nothing to uninstall: ${dest}\n` +
+        `  skill '${skillId}' is not installed under ${targetRoot}.` +
+        (installed.length ? `\n  installed here: ${installed.join(', ')}` : '')
+    );
+  }
+  if (!fs.existsSync(path.join(dest, 'SKILL.md'))) {
+    die(
+      `Refusing to uninstall: ${dest}\n` +
+        `  not a skill directory (missing SKILL.md) — will not delete arbitrary folders.`
+    );
+  }
+  fs.rmSync(dest, { recursive: true, force: true });
+  console.log(`Uninstalled ${skillId}`);
+  console.log(`  from ${dest}`);
+}
+
+function usageText() {
+  return `topmind-writing-skills — install TopMindspace agent skills
+
+Usage:
+  topmind-writing-skills list|ls
+  topmind-writing-skills install <skill-id> [--to|-t <dir>] [--force|-f]
+  topmind-writing-skills uninstall <skill-id> [--to|-t <dir>]
+  topmind-writing-skills help
+
+Behavior:
+  install    copies <skill-id>/ into <dir>/<skill-id>/. If the skill is already
+             installed, the installed version is reported and --force is required
+             to overwrite. Prints where/what-version/next-steps when done.
+  uninstall  removes <dir>/<skill-id>/ (refuses: not installed, not a skill
+             directory, or the package's own skill source).
+  No --to: the target directory is auto-detected (probe order below) and
+  printed explicitly in the install summary.
+
+Target probe order (no --to): ./.agents/skills, ./.claude/skills,
+  ./.cursor/skills, ./.codex/skills, ./.mimocode/skills, then
+  ~/.claude/skills, ~/.agents/skills, ~/.cursor/skills, ~/.codex/skills.
+
+Examples (npm recommended when published):
+  npx @topmindspace/topmind-writing-skills list
+  npx @topmindspace/topmind-writing-skills install topmind-briefs
+  npx @topmindspace/topmind-writing-skills install topmind-briefs --to ./.agents/skills
+  npx @topmindspace/topmind-writing-skills install topmind-briefs --force
+  npx @topmindspace/topmind-writing-skills uninstall topmind-briefs --to ./.agents/skills
+
+  # Follow repo HEAD:
+  npx github:topmindspace/topmind-writing-skills install topmind-briefs
+
+Privacy: the installer is fully local — it never collects or uploads anything.
+`;
+}
+
+function usage() {
+  console.log(usageText());
+}
+
+function main(argv) {
+  const args = argv.slice(2);
+  const cmd = args[0];
+
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    usage();
+    return;
+  }
+
+  if (cmd === 'list' || cmd === 'ls') {
+    const ids = listSkillIds();
+    if (!ids.length) {
+      console.log('No skills found in package.');
+      return;
+    }
+    for (const id of ids) {
+      const meta = readSkillMeta(id);
+      console.log(`${id}`);
+      if (meta.description) console.log(`  ${meta.description}…`);
+    }
+    return;
+  }
+
+  if (cmd === 'install') {
+    const skillId = args[1];
+    if (!skillId || skillId.startsWith('-')) {
+      die('Missing skill id.\n\n' + usageText());
+    }
+    let to = null;
+    let force = false;
+    for (let i = 2; i < args.length; i++) {
+      if (args[i] === '--to' || args[i] === '-t') {
+        to = args[++i];
+        if (!to) die('Option --to requires a directory path.');
+      } else if (args[i] === '--force' || args[i] === '-f') {
+        force = true;
+      } else {
+        die(`Unknown option: ${args[i]}\n\n` + usageText());
+      }
+    }
+    const targetRoot = to ? path.resolve(to) : resolveDefaultTarget();
+    install(skillId, targetRoot, { force, defaultTarget: !to });
+    return;
+  }
+
+  if (cmd === 'uninstall') {
+    const skillId = args[1];
+    if (!skillId || skillId.startsWith('-')) {
+      die('Missing skill id.\n\n' + usageText());
+    }
+    let to = null;
+    for (let i = 2; i < args.length; i++) {
+      if (args[i] === '--to' || args[i] === '-t') {
+        to = args[++i];
+        if (!to) die('Option --to requires a directory path.');
+      } else {
+        die(`Unknown option: ${args[i]}\n\n` + usageText());
+      }
+    }
+    const targetRoot = to ? path.resolve(to) : resolveDefaultTarget();
+    uninstall(skillId, targetRoot);
+    return;
+  }
+
+  die(`Unknown command: ${cmd}\n\n` + usageText());
+}
+
+main(process.argv);