skill-forge-hub 1.0.7 → 1.1.0

package/deck-stage/resources/skillforge-guide.txt

@@ -0,0 +1,131 @@
+# SkillForge 使用指引（技能锻造坊）
+
+SkillForge 是一套个人技能仓库 + 命令行分发器（npm 包 skill-forge-hub，命令 skill-forge）：把 21 个技能打包分发，一条命令装进你的 AI 助手技能目录；升级时配置版本感知，你的本地个性化配置永不丢失。
+
+## 一、SkillForge 是什么
+
+三个关键词：
+1、技能仓库：21 个技能按「最终产出什么」分七类（报表汇演 / 文档装裱 / 工程提效 / 演示汇演 / 数据整备 / 沟通协作 / 技能自造），每个技能都是 SKILL.md 薄入口 + resources/ 分册 + user-config.md 用户配置的规范结构
+2、命令行分发器：npm 包 skill-forge-hub，命令 skill-forge（ls / init / update），自动探测 AI 助手技能目录，交互或非交互安装
+3、配置保护：每个技能的用户配置出站在 user-config.md，升级永不覆盖；配置结构变化时备份 + 三选一，官方新配置另存对照文件供手动合并
+
+技能全景（21 个）：
+
+| 分类 | 技能 | 一句话触发语 |
+|:---|:---|:---|
+| 报表汇演 | daily-report | 「写日报」 |
+| 报表汇演 | weekly-report | 「写周报」 |
+| 报表汇演 | monthly-report | 「写月报」 |
+| 报表汇演 | quarterly-report | 「写季报」 |
+| 报表汇演 | annual-report | 「写年报」 |
+| 报表汇演 | team-report-collector | 「收日报」 |
+| 文档装裱 | article-to-html | 丢给它一个文档 |
+| 文档装裱 | twin-docs | 「翻译成英文文档」 |
+| 文档装裱 | one-pager | 「做张海报」 |
+| 工程提效 | spec-doc2spec | 「把这个文档转成需求规格」 |
+| 工程提效 | spec-spec2doc | 「把这个规格导出 Word/PDF」 |
+| 工程提效 | release-notes | 「写发版说明」 |
+| 演示汇演 | magic-deck | 「做个 PPT」（HTML 幻灯形态） |
+| 演示汇演 | deck-stage | 「做个 PPT」（.pptx 可编辑形态） |
+| 数据整备 | data-prepper | 「整理这份数据」 |
+| 数据整备 | commit-heatmap | 「生成提交热力图」 |
+| 沟通协作 | meeting-minutes | 「记会议」 |
+| 沟通协作 | prompt-pouch | 「做一个锦囊管理页面」 |
+| 沟通协作 | decision-log | 「记决策」 |
+| 技能自造 | meta-forge | 「帮我创建一个新技能」 |
+| 技能自造 | skill-doctor | 「给技能体检」 |
+
+## 二、命令速查
+
+| 命令 | 说明 |
+|:---|:---|
+| skill-forge ls | 列出全部技能（分类 + 名称 + 说明），只读不写文件 |
+| skill-forge init | 交互挑选安装：a 全装 / 编号挑选（已装标 ★）/ 确认时 s 跳过已装 |
+| npm update -g skill-forge-hub | 官方发新版后升级 CLI 本体（只升级本包） |
+| skill-forge update | 升级全部已安装技能（配置版本感知） |
+| skill-forge update --skills a,b | 只升级指定技能（未安装的提示跳过） |
+| skill-forge --version | 显示版本号 |
+| skill-forge --help | 显示完整帮助 |
+
+命令别名：list = ls、install = init、upgrade = update。
+
+通用参数（init / update 通用）：
+--target <目录>（-t）：指定技能目录；缺省自动探测常见助手目录（~/.qoder-cn、~/.claude、~/.cursor 等），探测到多个时交互选择
+--skills a,b（-s）：init 时跳过选择直接装指定技能（脚本与单件补装友好）；update 时只升级指定技能
+--yes（-y）：跳过确认直接执行；配置版本变化时默认「保留我的 + 官方版另存 .upstream 对照」
+
+## 三、场景化使用流程
+
+场景一 首次接入（从零到可用）：
+1、npm i -g skill-forge-hub
+2、skill-forge ls（先浏览清单，只读）
+3、skill-forge init（交互挑选）→ 输入 a 全装或编号挑选 → 确认时 s 跳过已装 → 自动探测技能目录 → 完成
+装完直接对话触发：「写日报」「写周报」「写月报」「写季报」「写年报」「记会议」，或直接丢给它一个文档。
+
+场景二 单件补装（脚本 / 只想要某一个）：
+skill-forge init --skills prompt-pouch --target ~/.qoder-cn/skills
+跳过挑选环节，只装指定技能到指定目录。
+
+场景三 官方发新版后升级：
+先 npm update -g skill-forge-hub（升级 CLI 本体），再 skill-forge update（全部）/ skill-forge update --skills daily-report（单个）
+· 配置结构没变：无感升级，user-config.md 原样保留
+· 配置结构变了（CONFIG_VERSION 升了）：先备份 user-config.md.bak-<时间戳>，再三选一——[1] 官方覆盖 / [2] 保留我的（默认，最稳，官方版另存 .upstream 对照文件手动合并）/ [3] 稍后处理
+· 官方删了文件：按 .installed-manifest 安装清单精准清理，你自建的文件一律不动
+
+场景四 非交互 / 自动化：
+skill-forge init --skills daily-report,weekly-report --yes
+--yes 跳过一切确认，配置冲突默认走 [2] 保留我的。
+
+场景五 换机器 / 换 AI 助手：
+新环境重新 npm i -g skill-forge-hub && skill-forge init；保留个人配置就把旧机器技能目录里的 user-config.md 一并拷过去（升级永不覆盖，覆盖安装时也保留）。
+
+## 四、典型技能使用链路
+
+统一节奏：安装 → 首次生成 → 修改配置 → 官方升级后 → 旧产物回炉。
+
+1、日报（报表族代表）：
+- 安装：skill-forge init --skills daily-report
+- 日常生成：说「写日报」口述内容 → md/txt/html（自动打开）+ 截图
+- 修改配置：user-config.md 改 DIR（落盘目录）/ THEME（五主题）/ TEMPLATE（自定义模板）；临时口头要求当次生效不写配置
+- 官方升级后：配置冲突选 [2] 保留我的，对照 .upstream 合并新配置点
+- 旧产物回炉：模板版本戳升了说「把我旧日报都升级成新样式」——浅升级换样式块、深升级从同目录 md 底稿重建，旧版先备份
+
+2、锦囊 prompt-pouch：
+- 安装：skill-forge init --skills prompt-pouch
+- 首次生成：「做一个锦囊管理页面」→ 生成管理台 html + data/prompts.json 数据文件
+- 日常使用：分组侧栏 / 搜索 / 收藏 / 标签点击过滤 / {变量} 插值一键复制 / 导入导出 JSON 备份；页面与数据分离，删页面不丢数据
+- 修改配置：user-config.md 改 DIR（页面目录）、DATA_DIR / BACKUP_DIR（数据与备份目录）
+- 官方升级后：数据目录与数据文件一概不动；深升级重建沿用原页 pouch-id → 收藏 / 分组照旧读回
+- 页面版本升级（回炉）：模板版本戳升了，下次生成时 AI 主动提示「检测到 X 份旧版锦囊」→ 说「把我旧锦囊都升级成新样式」→ 列清单选全部或部分 → 浅升级换样式块、深升级从模板重建沿用原页 pouch-id（收藏分组照旧读回）；prompts.json 数据不动、旧页先备份 .bak-时间戳
+- 多文件隔离：两份锦囊各自独立（内嵌 ID 命名空间）；复制文件副本 = 同一身份共享同一份数据（要独立身份请重新生成一份）
+
+3、PPT 两形态 magic-deck / deck-stage：
+- 选形态：说「做个 PPT」AI 先问——HTML 幻灯（magic-deck）还是 .pptx 可编辑文稿（deck-stage）
+- HTML 幻灯：magic-deck 生成单文件 HTML 幻灯，浏览器全屏放映（自动播放 / 循环 / 热键翻页）；需要图片时逐页 PNG 截图
+- .pptx 文稿：deck-stage 三问交互（素材 → 页骨架表 → 成片方式）生成 .pptx——常规页原生可编辑（数据卡 / 时间线 / 图表），封面与结尾页 HTML 截图保真
+- 补依赖：deck-stage 依赖 PptxGenJS，npm 包不含 node_modules，装完按提示 cd <技能目录>/deck-stage && npm install 补装一次
+- 修改配置：五主题 / 页面尺寸 / 演讲备注在 user-config.md
+
+4、会议纪要 meeting-minutes：
+- 日常生成：「记会议」口述材料 → 五段式纪要（会议信息 / 会议结论 / 议题讨论 / 决议与行动项 / 下次会议），行动项带负责人与截止时间——日报 / 周报 / 月报 / 季报的汇报链源头
+- 修改配置：SERIES_GROUP 三态——auto 自动提取系列名归入 meetings/{系列名}/、series 一律按系列建目录、off 纯月份平铺；改口机制「以后这个系列叫 XX」永久生效
+- 官方升级后：同报表族——配置三选一保护 + 说「把旧纪要升级成新样式」回炉
+
+## 五、通用小抄
+
+| 需求 | 做法 |
+|:---|:---|
+| 换落盘目录 / 主题 / 模板 | 改 user-config.md（升级永不覆盖） |
+| 官方发新版 | skill-forge update，配置冲突选 [2] 保留我的 |
+| 旧产物换新样式 | 说「把我旧 XX 都升级成新样式」 |
+| 装漏技能 | skill-forge init --skills 技能名 |
+| 查全部命令 | skill-forge --help |
+| 问单个技能用法 | 直接问「XX 技能怎么用」，AI 会读该技能的使用说明输出 |
+| 问 SkillForge 本身 | 问「skillforge 怎么用」，AI 朗读本指引并打开排版页 |
+
+## 六、常见问题
+
+1、装完对话没触发技能：确认装进了当前 AI 助手实际读取的技能目录（init 完成时输出的路径）
+2、deck-stage 报缺依赖：cd <技能目录>/deck-stage && npm install 补装 PptxGenJS 一次即可
+3、升级后配置会丢吗：不会。user-config.md（与 .preserve 清单内文件）升级永不覆盖，本地修改永久保留
+4、这份指引在哪：每个技能的 resources/ 目录里都有（skillforge-guide.txt 文字版 + skillforge-guide.html 排版版），官方升级时随技能资源一起更新

package/docs/architecture.en.md

@@ -10,9 +10,10 @@
 .
 ├── README.md                    # intro + output gallery + categories + skill list (English: README.en.md)
 ├── CHANGELOG.md                 # version changelog (English: CHANGELOG.en.md)
-├── docs/                        # docs (install / architecture / output screenshots; Chinese & English one-to-one)
+├── docs/                        # docs (install / architecture / usage examples / output screenshots; Chinese & English one-to-one)
 │   ├── install.md               # installation & upgrade in depth (English: install.en.md)
 │   ├── architecture.md          # this document (English: architecture.en.md)
+│   ├── usage-examples.md        # skill usage scenario examples (English: usage-examples.en.md)
 │   └── images/                  # output screenshots
 ├── cli.js                       # installer (ls / init / update, zero-dependency Node>=14)
 ├── package.json                 # npm package definition (skill-forge-hub, command name skill-forge)

package/docs/architecture.md

@@ -10,9 +10,10 @@
 .
 ├── README.md                    # 介绍 + 产物画廊 + 技能分类 + 技能清单（英文版 README.en.md）
 ├── CHANGELOG.md                 # 版本变更记录（英文版 CHANGELOG.en.md）
-├── docs/                        # 文档（安装升级 / 架构规范 / 产物截图，中英一一对应）
+├── docs/                        # 文档（安装升级 / 架构规范 / 使用示例 / 产物截图，中英一一对应）
 │   ├── install.md               # 安装与升级详解（英文版 install.en.md）
 │   ├── architecture.md          # 本文档（英文版 architecture.en.md）
+│   ├── usage-examples.md        # 技能使用场景示例（英文版 usage-examples.en.md）
 │   └── images/                  # 产物成品截图
 ├── cli.js                       # 安装器（ls / init / update，零依赖 Node>=14）
 ├── package.json                 # npm 包定义（skill-forge-hub，命令名 skill-forge）

package/docs/install.en.md

@@ -10,6 +10,7 @@
 npm i -g skill-forge-hub
 skill-forge ls        # list all skills & descriptions (read-only)
 skill-forge init      # interactive skill picker, auto-detects & installs to the AI assistant's skill directory
+npm update -g skill-forge-hub    # upgrade the CLI itself after a release (this package only)
 skill-forge update    # upgrade installed skills (config-version aware, see below)
 ```
 
@@ -54,6 +55,61 @@ Common flags (for init / update):
 
 Command aliases: `list` = `ls`, `install` = `init`, `upgrade` = `update`.
 
+## Scenario Walkthroughs
+
+### Scenario 1: first-time setup (zero to working)
+
+```bash
+npm i -g skill-forge-hub     # 1. global install of the CLI
+skill-forge ls               # 2. browse the skill list first (read-only, writes nothing)
+skill-forge init             # 3. interactively pick the skills to install
+```
+
+How `skill-forge init` works: lists every skill (category + name + one-line description) → type `a` to install all, or type numbers to pick (e.g. `1,3,5`; installed skills are marked ★) → on confirm, type `s` to skip installed and install only new ones → auto-detect the AI assistant's skill directory (pick by number when several are found) → done.
+
+After that, just talk to it: "write a daily report", "write a weekly report", "write a monthly report", "write a quarterly report", "write an annual report", "take meeting minutes", or hand it a document.
+
+### Scenario 2: single-skill install (scripts / just one)
+
+```bash
+skill-forge init --skills prompt-pouch --target ~/.qoder-cn/skills
+```
+
+Skips the picker and installs exactly the named skill to the named directory — good for scripting, CI, or topping up a single skill.
+
+### Scenario 3: upgrading after an official release
+
+```bash
+npm update -g skill-forge-hub                    # first upgrade the CLI itself (this package only)
+skill-forge update                              # then upgrade all installed skills
+skill-forge update --skills daily-report        # upgrade just one
+```
+
+- **Config structure unchanged**: silent upgrade — skill files update, your `user-config.md` stays untouched
+- **Config structure changed** (official `CONFIG_VERSION` bumped): your config is first backed up as `user-config.md.bak-<timestamp>`, then a three-way choice:
+  - `[1] official overwrite`: take the fresh official config (your old one is recoverable from the backup)
+  - `[2] keep mine` (default, safest): your config stays, the official version is saved as `user-config.md.upstream` for you to compare and merge new config points manually
+  - `[3] decide later`: skip this time, no companion file generated
+- **Official files deleted**: cleaned up precisely via the `.installed-manifest` (only files the official version deleted, plus now-empty directories); your self-created files are never touched
+
+### Scenario 4: non-interactive / automation
+
+```bash
+skill-forge init --skills daily-report,weekly-report --yes
+```
+
+`--yes` skips every confirmation; on config-version conflict it defaults to `[2] keep mine` (the safest branch).
+
+### Scenario 5: new machine / new AI assistant
+
+Run `npm i -g skill-forge-hub && skill-forge init` in the new environment; to carry your personal config over, copy the old `user-config.md` from the previous skill directory (never overwritten on upgrade, kept on install too).
+
+### FAQ
+
+- **Skills don't trigger after install**: check the CLI installed into the skill directory your AI assistant actually reads (the path printed when init finishes)
+- **deck-stage complains about a missing dependency**: run `cd <skill dir>/deck-stage && npm install` once for PptxGenJS
+- **Will upgrades wipe my config**: never. `user-config.md` (and `.preserve`-listed files) are never overwritten on upgrade — your local edits persist forever
+
 ## Upgrade & Config Protection
 
 `skill-forge update` (all installed skills by default, or `--skills a,b`) protects your config before overwriting any skill files.

package/docs/install.md

@@ -10,6 +10,7 @@
 npm i -g skill-forge-hub
 skill-forge ls        # 列出全部技能与说明（只读）
 skill-forge init      # 交互式挑选技能，自动探测并安装到 AI 助手技能目录
+npm update -g skill-forge-hub    # 官方发新版后升级 CLI 本体（只升级本包）
 skill-forge update    # 升级已安装技能（配置版本感知，见下）
 ```
 
@@ -54,6 +55,61 @@ cp -R spec-doc2spec spec-spec2doc <你的 AI 助手技能目录>/
 
 命令别名：`list` = `ls`、`install` = `init`、`upgrade` = `update`。
 
+## 场景化使用流程
+
+### 场景一：新用户首次接入（从零到可用）
+
+```bash
+npm i -g skill-forge-hub     # 1. 全局安装 CLI
+skill-forge ls               # 2. 先浏览技能清单（只读，不写任何文件）
+skill-forge init             # 3. 交互式挑选要装的技能
+```
+
+`skill-forge init` 的交互过程：列出全部技能（分类 + 名称 + 一句话说明）→ 输入 `a` 全装，或输入编号挑选（如 `1,3,5`，已装技能标 ★）→ 确认时输 `s` 跳过已装、只装新技能 → 自动探测 AI 助手技能目录（探测到多个时按编号选择）→ 完成安装。
+
+装完即可直接对话触发：「写日报」「写周报」「写月报」「写季报」「写年报」「记会议」，或直接丢给它一个文档。
+
+### 场景二：单件补装（脚本 / 只想要某一个）
+
+```bash
+skill-forge init --skills prompt-pouch --target ~/.qoder-cn/skills
+```
+
+跳过挑选环节，只装指定技能到指定目录——适合脚本化、CI 或补装单个技能。
+
+### 场景三：官方发新版后升级
+
+```bash
+npm update -g skill-forge-hub                    # 先升级 CLI 本体（只升级本包）
+skill-forge update                              # 再升级全部已装技能
+skill-forge update --skills daily-report        # 只升级某一个
+```
+
+- **配置结构没变**：无感升级——技能文件更新，你的 `user-config.md` 原样保留
+- **配置结构变了**（官方 `CONFIG_VERSION` 升了）：先自动备份 `user-config.md.bak-<时间戳>`，再交互三选一：
+  - `[1] 官方覆盖`：换成全新官方配置（旧配置随时可从备份找回）
+  - `[2] 保留我的`（默认，最安全）：你的配置不动，官方新版另存 `user-config.md.upstream` 对照文件，自己对比后按需合并新配置点
+  - `[3] 稍后处理`：本次跳过，不生成对照文件
+- **官方删了文件**：按 `.installed-manifest` 安装清单精准清理官方已删除的文件与空目录；你自建的文件一律不动
+
+### 场景四：非交互 / 自动化
+
+```bash
+skill-forge init --skills daily-report,weekly-report --yes
+```
+
+`--yes` 跳过一切确认；配置版本冲突时默认走 `[2] 保留我的`（最安全分支）。
+
+### 场景五：换机器 / 换 AI 助手
+
+新环境重新 `npm i -g skill-forge-hub && skill-forge init` 即可；要保留个人配置，把旧机器技能目录里的 `user-config.md` 一并拷过去（升级永不覆盖，覆盖安装时也保留）。
+
+### 常见问题
+
+- **装完对话没触发技能**：确认装进了当前 AI 助手实际读取的技能目录（`init` 完成时输出的路径）
+- **deck-stage 报缺依赖**：`cd <技能目录>/deck-stage && npm install` 补装 PptxGenJS 一次即可
+- **升级后配置会丢吗**：不会。`user-config.md`（与 `.preserve` 清单内文件）升级永不覆盖，本地修改永久保留
+
 ## 升级与配置保护
 
 `skill-forge update`（默认升级全部已装技能，可用 `--skills a,b` 指定）在覆盖技能文件前自动保护你的配置。

package/docs/usage-examples.en.md

@@ -0,0 +1,50 @@
+# Skill Usage Examples
+
+[中文](usage-examples.md)
+
+> End-to-end examples, from install to everyday use. Four representative skills are picked: daily-report (representative of the report family, covering config tweaks and output reforge), prompt-pouch (local console, covering user data and multi-file isolation), magic-deck & deck-stage (both PPT forms, covering intent routing and dependency install), meeting-minutes (source of the reporting chain, covering series grouping). The other skills share the same shape as these four — easy to generalize.
+
+Every example follows the same rhythm: **install → first generation → config tweaks → what to do after an official upgrade → output reforge**.
+
+## Example 1: daily-report (representative of the report family)
+
+1. **Install**: `skill-forge init --skills daily-report`
+2. **First generation**: just say "write a daily report", describe what you did today (or hand it a paragraph / a file / an image) → produces `daily-report-YYYYMMDD.md` + `.txt` + `.html` (auto-opened), plus a full-page content-png capture
+3. **Config tweaks**: ask the AI to open the skill's `user-config.md` and change `DIR` (save directory), `THEME` (tech/biz/mono/light/warm five themes), `TEMPLATE: custom` for a custom template; ad-hoc verbal requests ("only 3 items today") apply once and never touch config
+4. **After an official upgrade**: `npm update -g skill-forge-hub` (upgrade the CLI itself) → `skill-forge update` (upgrade the skills) → if the official config structure changed, it backs up first then offers a three-way choice; pick `[2] keep mine`, then compare `user-config.md.upstream` and merge new config points manually (e.g. a new DATA_SOURCES list)
+5. **Output reforge**: when the official template stamp bumped (`sf-template@N`) → the next generation says "found X old daily reports" → say "upgrade all my old daily reports to the new style" → pick all or some → shallow upgrade (style changes) swaps style blocks, deep upgrade (structure changes) rebuilds from the sibling md draft, old version backed up first
+
+## Example 2: prompt-pouch (local console + user data)
+
+1. **Install**: `skill-forge init --skills prompt-pouch`
+2. **First generation**: "make me a prompt management page" → produces the console html + `data/prompts.json`
+3. **Everyday use**: group sidebar / search / favorites / tag click filtering / `{variable}` interpolation one-click copy / JSON import & export / group emoji quick panel; data lives in `data/prompts.json` with rolling backups in `backup/` — page and data are separated, deleting the page never loses data
+4. **Config tweaks**: in `user-config.md`, change `DIR` (page directory), `DATA_DIR` / `BACKUP_DIR` (data & backup directories)
+5. **After an official upgrade**: the data directory and data files are never touched; a deep rebuild keeps the page's original pouch-id → existing favorites / groups read back unchanged
+6. **Page-version upgrade (reforge)**: when the official template bumps (version stamp sf-template@N +1), the next "make a prompt management page" run has the AI proactively say "skill template upgraded to vN, found X old pouches" — say "upgrade all my old pouches to the new style" → the AI lists them (file / old version / has user data) → pick all or some → upgrade one by one: style-only changes swap the style block and scripts (shallow), structural changes rebuild from the template but keep the original pouch-id (deep — favorites and groups read back unchanged); prompts.json is never touched and the old page is backed up as .bak-<timestamp> first → three-part report (✅ upgraded / ⚠️ hand-edits kept / 🟡 failure reasons); pure wording polish does not bump the stamp — no reforge needed
+7. **Multi-file isolation**: two pouches stay independent (embedded-ID namespacing, no cross-talk); copying a file = same identity sharing the same data (for an independent identity, generate a new one — don't copy a file to fake a new output)
+
+## Example 3: magic-deck + deck-stage (both PPT forms)
+
+1. **Intent routing**: saying "make a PPT" prompts the AI to ask the form first — HTML slides (magic-deck) or an editable .pptx (deck-stage)
+2. **magic-deck**: produces a single-file HTML slide deck → open in the browser for fullscreen playback (autoplay / loop / hotkey paging) → per-page PNG captures when images are needed
+3. **deck-stage**: three-question interaction (materials → page skeleton table → build method) → produces a .pptx: regular pages natively editable (data cards / timelines / charts), cover & closing pages captured losslessly from HTML
+4. **Dependency**: deck-stage needs PptxGenJS — the npm package excludes node_modules, so after install run `cd <skill dir>/deck-stage && npm install` once as prompted
+5. **Config**: the five themes (tech/biz/mono/light/warm), page size, speaker-notes switch etc. all live in `user-config.md`
+
+## Example 4: meeting-minutes (source of the reporting chain)
+
+1. **Install**: `skill-forge init --skills meeting-minutes`
+2. **First generation**: "take meeting minutes" → describe the meeting materials → five-section minutes (meeting info / conclusions / agenda discussion / resolutions & action items / next meeting), action items with owners and deadlines — these action items are the source of the chain that daily / weekly / monthly / quarterly reports cite
+3. **Series grouping**: `SERIES_GROUP` three states — `auto` extracts series names into `meetings/{series}/`, `series` always uses series directories, `off` flat month directories; rename mechanism: "always call this series XX" persists
+4. **After an official upgrade**: same as the report family — three-way config protection + minutes reforge (say "upgrade my old minutes to the new style")
+
+## Cheat Sheet
+
+| Need | Do |
+|:---|:---|
+| Change save dir / theme / template | Edit `user-config.md` (never overwritten on upgrade) |
+| Official release is out | first `npm update -g skill-forge-hub` (the CLI itself), then `skill-forge update`; on config conflict pick `[2] keep mine` |
+| Restyle old outputs | Say "upgrade all my old XX to the new style" |
+| A skill is missing | `skill-forge init --skills <skill-name>` |
+| See all commands | `skill-forge --help` |

package/docs/usage-examples.md

@@ -0,0 +1,50 @@
+# 技能使用示例
+
+[English](usage-examples.en.md)
+
+> 从安装到日常使用的完整链路示例。挑选四个代表性技能：日报（报表族代表，覆盖配置修改与旧产物回炉）、锦囊（本地管理台，覆盖用户数据与多文件隔离）、魔法幻灯与登台（PPT 两种形态，覆盖意图分流与依赖补装）、会议纪要（汇报链源头，覆盖系列分组）。其余技能形态与这四个同构，可举一反三。
+
+每个示例按同一节奏展开：**安装 → 首次生成 → 修改配置 → 官方升级后的操作 → 旧产物升级（回炉）**。
+
+## 示例一：daily-report 日报（报表族代表）
+
+1. **安装**：`skill-forge init --skills daily-report`
+2. **首次生成**：直接说「写日报」，口述今天干了什么（或丢一段文字 / 一个文件 / 一张图）→ 生成 `daily-report-YYYYMMDD.md` + `.txt` + `.html`（自动打开），附整页截图 content-png
+3. **修改配置**：让 AI 打开技能目录的 `user-config.md`，改 `DIR`（落盘目录）、`THEME`（tech/biz/mono/light/warm 五主题）、`TEMPLATE: custom` 换自定义模板；临时口头要求（如「今天只写 3 条」）当次生效、不写配置
+4. **官方升级后**：`npm update -g skill-forge-hub`（升级 CLI 本体）→ `skill-forge update`（升级技能）→ 若官方配置结构变了，先自动备份再交互三选一，选 `[2] 保留我的`，然后对照 `user-config.md.upstream` 手动合并新配置点（如新增的 DATA_SOURCES 数据源清单）
+5. **旧产物回炉**：官方模板版本戳升了（`sf-template@N`）→ 下次生成时提示「检测到 X 份旧版日报」→ 说「把我旧日报都升级成新样式」→ 选全部或部分 → 浅升级（样式变化）替换样式块、深升级（结构变化）从同目录 md 底稿重建，旧版先备份
+
+## 示例二：prompt-pouch 锦囊（本地管理台 + 用户数据）
+
+1. **安装**：`skill-forge init --skills prompt-pouch`
+2. **首次生成**：「做一个锦囊管理页面」→ 生成锦囊管理台 html + `data/prompts.json` 数据文件
+3. **日常使用**：分组侧栏 / 搜索 / 收藏 / 标签点击过滤 / `{变量}` 插值一键复制 / 导入导出 JSON 备份 / 分组 emoji 快捷面板；数据存 `data/prompts.json`、滚动备份在 `backup/`——页面与数据分离，删页面不丢数据
+4. **修改配置**：`user-config.md` 改 `DIR`（页面目录）、`DATA_DIR` / `BACKUP_DIR`（数据与备份目录）
+5. **官方升级后**：数据目录与数据文件一概不动；深升级重建沿用原页 pouch-id → 原有收藏 / 分组照旧读回
+6. **页面版本升级（回炉）**：官方模板升级（版本戳 sf-template@N +1）后，下次「做一个锦囊管理页面」时 AI 主动提示「技能模板已升级至 vN，检测到 X 份旧版锦囊」——说「把我旧锦囊都升级成新样式」→ AI 列清单（文件 / 旧版本 / 有无用户数据）→ 选全部或部分 → 逐份升级：样式类变化替换 style 块与脚本（浅升级）、结构类变化从模板重建但沿用原页 pouch-id（深升级，收藏分组照旧读回），prompts.json 数据一概不动、旧页先备份 .bak-时间戳 → 报告三段式（✅ 已升级 / ⚠️ 手改保留 / 🟡 失败原因）；纯措辞润色不升版本戳，无需回炉
+7. **多文件隔离**：两份锦囊各自独立（内嵌 ID 命名空间，互不串台）；复制文件副本 = 同一身份共享同一份数据（要独立身份请重新生成一份，勿复制文件冒充新产物）
+
+## 示例三：magic-deck + deck-stage（PPT 两种形态）
+
+1. **意图分流**：说「做个 PPT」时，AI 会先问形态——HTML 幻灯（magic-deck）还是 .pptx 可编辑文稿（deck-stage）
+2. **magic-deck**：生成单文件 HTML 幻灯 → 浏览器打开全屏放映（自动播放 / 循环 / 热键翻页）→ 需要图片时逐页 PNG 截图
+3. **deck-stage**：三问交互（素材 → 页骨架表 → 成片方式）→ 生成 .pptx：常规页原生可编辑（数据卡 / 时间线 / 图表），封面与结尾页 HTML 截图保真
+4. **依赖补装**：deck-stage 依赖 PptxGenJS——npm 包不含 node_modules，装完按提示 `cd <技能目录>/deck-stage && npm install` 补装一次
+5. **配置**：五主题（tech/biz/mono/light/warm）、页面尺寸、演讲备注开关等均在 `user-config.md`
+
+## 示例四：meeting-minutes 会议纪要（汇报链源头）
+
+1. **安装**：`skill-forge init --skills meeting-minutes`
+2. **首次生成**：「记会议」→ 口述会议材料 → 五段式纪要（会议信息 / 会议结论 / 议题讨论 / 决议与行动项 / 下次会议），行动项带负责人与截止时间——这份行动项就是后续日报 / 周报 / 月报 / 季报的汇报链源头
+3. **系列分组**：`SERIES_GROUP` 三态——`auto` 自动提取系列名归入 `meetings/{系列名}/`、`series` 一律按系列建目录、`off` 纯月份平铺；改口机制：「以后这个系列叫 XX」永久生效
+4. **官方升级后**：同报表族——配置三选一保护 + 旧纪要回炉（说「把旧纪要升级成新样式」）
+
+## 通用小抄
+
+| 需求 | 做法 |
+|:---|:---|
+| 换落盘目录 / 主题 / 模板 | 改 `user-config.md`（升级永不覆盖） |
+| 官方发新版 | 先 `npm update -g skill-forge-hub`（CLI 本体）再 `skill-forge update`，配置冲突选 `[2] 保留我的` |
+| 旧产物换新样式 | 说「把我旧 XX 都升级成新样式」 |
+| 装漏技能 | `skill-forge init --skills 技能名` |
+| 看全部命令 | `skill-forge --help` |

package/magic-deck/SKILL.md

@@ -25,7 +25,7 @@ disable-model-invocation: false
    - Playwright headless 自检（缺则 `pip3 install --user playwright`；用系统 Chrome，无需 playwright install 下载浏览器）：`p.chromium.launch(channel="chrome", headless=True)` → goto 页面 → 挂 pageerror 监听（零容忍）→ 按页数循环 `go(i)` 把每一页翻完
    - 截首 / 中 / 末三页 PNG，Read 自查：版式正常、文字无溢出截断、图表数据到位、无豆腐块缺字
    - 任何报错或视觉问题：修 HTML → 重检；全绿才进第 3 步
-3. **落盘与命名**：自检通过后在 DIR 下新建 `{文件名}/` 子目录（`mkdir -p`，总目录统一管理、各次产出自包含互不干扰），`cp` 到该子目录，自动打开浏览器供用户放映。命名三级优先：①用户口头指定文件名 → 用指定名；②未指定且 FILENAME=auto → 按本次内容主题+用途总结中文名（如「智能探针系统-产品介绍」，让用户日后能按名找回继续改）；③FILENAME 写死固定名 → 用固定名。重名一律自动加日期后缀，绝不覆盖；落盘目录复用不清空、不改动目录内既有文件
+3. **落盘与命名**：自检通过后在 DIR 下新建 `{文件名}/` 子目录（`mkdir -p`，总目录统一管理、各次产出自包含互不干扰），`cp` 到该子目录，自动打开浏览器供用户放映。命名三级优先：①用户口头指定文件名 → 用指定名；②未指定且 FILENAME=auto → 按本次内容主题+用途总结中文名（如「智能探针系统-产品介绍」，让用户日后能按名找回继续改）；③FILENAME 写死固定名 → 用固定名。重名一律自动加日期后缀，绝不覆盖；落盘目录复用不清空、不改动目录内既有文件；落盘完成后对话回复必须向用户报告落盘位置：完整路径（DIR/{文件名}/ 子目录）与文件清单（html 与预览截图），并注明浏览器是否已自动打开
 4. **使用咨询**（用户只问「怎么用 / 使用说明 / 能干什么」等用法、未要求生成）→ 读 `resources/usage-guide.md`，将其内容原样输出（首行标题改为「魔法幻灯生成器使用指南」），不生成 HTML
 
 
@@ -84,3 +84,13 @@ disable-model-invocation: false
 - 修改本 skill 任何文件后，必须 grep 全文核对：新词已命中、旧词零残留（改一处查一处）
 - 修改 HTML 效果必须双处同步：`resources/reference.html` 与 `resources/deck-spec.md` 对应描述同时更新，禁止只改一处
 - 修改配置键必须三处同步：user-config.md 的 yaml、SKILL.md 配置键清单、deck-spec.md 对应规则
+
+
+---
+
+## 🔍 SkillForge 使用指引（整体咨询时触发）
+
+当用户询问 **SkillForge 本身**（不是单个技能用法）——「skillforge 怎么用 / 使用说明 / 使用指引 / 是什么」「技能怎么安装 / 怎么升级 / 装了哪些技能 / 技能清单」「skill-forge ls / init / update 等命令怎么用」「技能安装器 / 技能锻造坊」等（中英文、近似说法均可，关键词可自由扩展）：
+1. Read 同目录 `resources/skillforge-guide.txt` 全文，按其内容整理回答（命令与参数以 txt 为准，勿自行编造）
+2. 用系统命令打开同目录 `resources/skillforge-guide.html`（macOS `open`，Windows `start`），让用户在浏览器看排版版
+3. 用户只问单个技能怎么用时（如「日报怎么用」）不触发本指引，走本技能的使用说明

package/magic-deck/resources/deck-spec.md

@@ -6,7 +6,7 @@
 
 ## 0. 铁律
 
-- **单文件零依赖**：禁用 CDN/@import/外链 CSS/JS/图片/网络字体，双击离线可打开；字体用系统栈 `ui-monospace,'SF Mono',SFMono-Regular,Menlo,Consolas,'Microsoft YaHei',monospace`
+- **单文件零依赖**：禁用 CDN/@import/外链 CSS/JS/图片/网络字体，双击离线可打开；字体用系统栈 `ui-monospace,'SF Mono',SFMono-Regular,Menlo,Consolas,monospace`
 - **舞台 1280×720（16:9）**，按窗口等比缩放（--sc），窗口任意大小不变形
 - **截图与复制只含主体**：截图克隆当前 slide、复制取 slide innerText，绝不包含工具栏/页码/箭头/提示等操作元素
 - **全屏纯净**：`:root:fullscreen` 下所有操作元素与背景氛围层（.bg-glow/.bg-grid）全部隐藏、页面底色纯黑 `#000`，只留舞台主体（与 PPT 软件放映一致：幻灯按比例充满画面，比例不匹配处补黑边，绝无主题氛围边框/光斑/网格）

package/magic-deck/resources/reference.html

@@ -10,7 +10,7 @@
 /* ══════════ 0. 基础 ══════════ */
 *{ margin:0; padding:0; box-sizing:border-box; }
 html,body{ width:100%; height:100%; overflow:hidden;
-  font-family:ui-monospace,'SF Mono',SFMono-Regular,Menlo,Consolas,'Microsoft YaHei',monospace; }
+  font-family:ui-monospace,'SF Mono',SFMono-Regular,Menlo,Consolas,monospace; }
 button,select,input{ font-family:inherit; }
 /* ══════════ 1. 十六主题 CSS 变量（12 令牌 × 16 主题，默认 tech） ══════════ */
 :root, [data-theme="tech"]{