skill-forge-hub 1.0.7 → 1.2.0

package/docs/articles/ai-prompt-management-skill-pouch.md

@@ -0,0 +1,37 @@
+# 用 AI 技能包管提示词：把散落的灵光收进一只锦囊
+
+> 关键词：提示词管理 / Agent Skills / AI 技能包 / 锦囊 prompt-pouch
+> 仓库：[SkillForge](https://github.com/windfallsheng/SkillForge) · 技能简介：[SKILLS_CATALOG.md#prompt-pouch](../../SKILLS_CATALOG.md)
+
+好提示词是资产。但大多数人的提示词过着流浪生活——散落在聊天记录、备忘录、收藏夹、转发消息里。当时灵光一闪写下的那段精妙引导，三个月后想再用，翻遍历史找不到，只能凭记忆重写，还得从头调教。
+
+「锦囊」（prompt-pouch）就是为这件事造的 AI 技能：一个本地 HTML 管理台，把提示词按分组收纳、全文搜索、一键复制，还能给提示词留 {变量} 插值位——同一段模板，填入不同对象就能反复复用。下面是一套十分钟上手流程。
+
+## 第一步：安装（一分钟）
+
+```bash
+npm i -g skill-forge-hub
+skill-forge init        # 交互勾选 prompt-pouch
+```
+
+也可以不从 CLI 装：直接把仓库里的 `prompt-pouch/` 目录复制进你 AI 助手的技能目录，效果相同。技能就是一份薄薄的 SKILL.md 加资源文件，与宿主无关。
+
+## 第二步：初始化（一句话）
+
+对 AI 说「建一个锦囊」。它会在你指定的目录生成两个东西：管理页面 `prompt-pouch.html` 和真相源 `data/prompts.json`。页面负责展示，数据负责记忆，两者严格分离——这是后面一切安全的根。
+
+## 第三步：开始收藏（口述即可）
+
+不用打开编辑器。对 AI 说「把这段话加进锦囊」——比如把某次对话里验证过的那段「角色设定 + 输出格式」整段收进去，它替你写进 JSON；刷新页面即见。当然也可以直接在页面表单里手动录入。
+
+## 第四步：用起来
+
+管理台该有的都有：分组侧栏（带计数徽章）、关键词搜索（命中高亮）、收藏星标、标签点击过滤、四种排序（手动拖拽可用）、JSON 导入导出备份、使用频率统计。挑提示词时看频率，就知道哪些真正好用。
+
+## 为什么做成「技能」而不是「应用」
+
+关键差别在宿主中立。锦囊今天在 Qoder 里用，明天换 Claude Code、Cursor，复制过去同样能唤起，数据 JSON 原样带走。提示词是你的，不是某个工具的。
+
+## 结语
+
+提示词管理的正确姿势，不是「记住更好的提示词」，而是让每条好提示词都有一个回得来的家。锦囊的每一张卡片，都是一次被验证过的对话起点。

package/docs/directory-submission.md

@@ -0,0 +1,106 @@
+# 目录收录素材包 · Directory Submission Kit
+
+> 本文件汇总 SkillForge 提交技能目录（skills.sh / awesome-claude-skills）所需的全部素材与操作指引。
+> 当前状态：**素材已就绪**，提交动作（提 PR / 发布 / 改 topics）需账户授权，按下方指引一步到位。
+
+## 三动作执行状态
+
+| 动作 | 状态 | 落点 |
+|:---|:---|:---|
+| ① 提交进 skills.sh 与 awesome-claude-skills | 素材就绪，待授权执行 | 本文件 |
+| ② 每技能独立可引用简介 | ✅ 已完成 | [SKILLS_CATALOG.md](../SKILLS_CATALOG.md) |
+| ③ 实操文章 | ✅ 已完成 | [articles/ai-prompt-management-skill-pouch.md](articles/ai-prompt-management-skill-pouch.md)、[articles/ai-daily-report-correct-pose.md](articles/ai-daily-report-correct-pose.md) |
+
+---
+
+## 通道 A：awesome-claude-skills（PR 制目录）
+
+收录方式：fork 目录仓库 → 按目录格式追加条目 → 提 PR。条目文案直接摘录 [SKILLS_CATALOG.md](../SKILLS_CATALOG.md) 对应锚点（每技能一段，独立成文）。
+
+### A1. 条目素材（英文，可直接整段摘录）
+
+```markdown
+| [SkillForge](https://github.com/windfallsheng/SkillForge) | 21 reusable agent skills (SKILL.md entry, host-agnostic) spanning reporting (daily/weekly/monthly/quarterly/annual + team collector), document beautification (Word→HTML, bilingual twin docs, one-page posters), engineering (Pandoc doc↔spec, release notes), presentations (HTML decks + editable PPTX), data prep (Excel/CSV cleaning, git heatmaps), collaboration (meeting minutes, prompt management console, decision logs) and meta-skills (skill forge + health check). Fully offline, zero external dependencies, user config isolated in user-config.md. One-line install: `npm i -g skill-forge-hub && skill-forge init`. |
+```
+
+> 若目录按单技能分行，则摘录对应锚点，如 `SKILLS_CATALOG.md#daily-report` / `#prompt-pouch` / `#one-pager`（建议先提交旗舰技能 3-5 个，再逐步扩列）。
+
+### A2. PR 标题与描述模板
+
+```
+Title: Add SkillForge — 21-skill craft workshop (reports / docs / decks / data / collaboration)
+
+## Summary
+SkillForge is a workshop of 21 reusable agent skills, each a thin SKILL.md entry
+plus stage-split resources, host-agnostic across Claude Code / Cursor / Qoder / etc.
+
+## Highlights
+- Report family: daily / weekly / monthly / quarterly / annual reports + team daily collector,
+  12-industry glossary, natural-language dates, custom templates
+- prompt-pouch: local HTML prompt management console ({variable} interpolation, groups,
+  search, tags, JSON backup)
+- one-pager: 32 layout templates × 25 themes (800 combos) one-screen HTML posters
+- All offline, zero external dependencies; user config isolated (upgrades never overwrite)
+
+## Links
+- Repo: https://github.com/windfallsheng/SkillForge
+- Per-skill bilingual profiles: https://github.com/windfallsheng/SkillForge/blob/main/SKILLS_CATALOG.md
+```
+
+### A3. 操作步骤（两条路任选）
+
+**路径 1：gh CLI**（先登录，见文末「gh 登录指引」）
+
+```bash
+gh auth login                          # 一次性登录
+gh repo fork ComposioHQ/awesome-claude-skills --clone
+# 编辑 README 追加条目（用 A1 素材）
+gh pr create --title "Add SkillForge — 21-skill craft workshop" --body-file pr-body.md
+```
+
+**路径 2：网页操作**：GitHub 打开目录仓库 → Fork → 在线编辑 README 追加条目 → Create pull request（描述贴 A2 模板）。
+
+---
+
+## 通道 B：skills.sh（自动索引，收录需发布）
+
+### B1. 收录机制（probe 结论）
+
+skills.sh 由 Vercel 运营，**无 PR 提交入口**：它索引每一个通过 open skills CLI（vercel-labs/skills）生态公开发布的技能。SkillForge 当前以 npm 包 `skill-forge-hub` + GitHub 仓库形态存在，要进 skills.sh 索引，需以 open skills 兼容形态发布技能包。
+
+### B2. 发布步骤（⚠️ 发布动作，需拍板后执行）
+
+```bash
+# 1. 为技能补 open skills 元数据（skills.json / 每技能 frontmatter 对齐 open skills 规范）
+# 2. 用 open skills CLI 发布（自动进 skills.sh 索引）
+npx skills publish
+# 3. 验证：skills.sh 搜索 skill-forge / daily-report 可见
+```
+
+> 受「未获用户明确指示不得发版本」纪律约束：此通道在用户明确同意发布前不执行。
+
+---
+
+## 通道 C：零成本加码（无授权门槛，建议随 PR 一起做）
+
+1. **GitHub topics**（提高目录与搜索权重，网页 Settings 或 CLI 一键）：
+
+```bash
+gh repo edit windfallsheng/SkillForge   --add-topic claude-skills --add-topic agent-skills --add-topic claude-code   --add-topic cursor --add-topic ai-agents --add-topic productivity   --add-topic prompt-management --add-topic reporting
+```
+
+2. **文章分发**：将 [docs/articles/](articles/) 两篇转载到掘金 / 知乎 / 博客园，文末带仓库链接（搜索语料 + 引用锚点）。
+
+---
+
+## 附：gh 登录指引
+
+```bash
+gh auth login
+# 交互选择：GitHub.com → HTTPS 或 SSH → Authenticate Git with your GitHub credentials
+#   → Login with a web browser（推荐）→ 复制一次性 code 到浏览器完成授权
+# 验证：
+gh auth status
+```
+
+登录后即可执行通道 A 与通道 C 的全部命令。

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,13 +55,68 @@ 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.bak-<timestamp>.md`, 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.upstream.md` 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.
 
 - **Always preserved**: an existing `user-config.md` in the target directory (and any files declared in the skill's `.preserve` list) is never overwritten — your local config persists forever; when the official config gains updates, a `.upstream` companion file is saved so you can merge new config points manually
 - **Version aware**: when the official `user-config.md` declares a `CONFIG_VERSION` on its first line higher than your local version (config structure grew / shrank / was renamed) —
-  1. your config is first backed up as `user-config.md.bak-<timestamp>`
+  1. your config is first backed up as `user-config.bak-<timestamp>.md`
   2. interactive three-way choice: `[1] official overwrite` (old config recoverable from the backup) / `[2] keep mine` + official copy saved as `.upstream` (default) / `[3] decide later` (no companion file generated this time)
   3. `--yes` or non-interactive environments default to `[2]`, the safest option
 - **Version match**: silent upgrade — only skill files are updated, config stays untouched

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,13 +55,68 @@ 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.bak-<时间戳>.md`，再交互三选一：
+  - `[1] 官方覆盖`：换成全新官方配置（旧配置随时可从备份找回）
+  - `[2] 保留我的`（默认，最安全）：你的配置不动，官方新版另存 `user-config.upstream.md` 对照文件，自己对比后按需合并新配置点
+  - `[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` 指定）在覆盖技能文件前自动保护你的配置。
 
 - **常驻保护**：目标目录已存在的 `user-config.md`（及技能 `.preserve` 清单声明的文件）永不被覆盖，你的本地配置永久保留；官方配置内容有更新时另存 `.upstream` 对照文件，可按需手动合并新配置点
 - **版本感知**：官方 `user-config.md` 首行的 `CONFIG_VERSION` 高于你的本地版本（配置结构增/减/改名）时——
-  1. 先把你的配置备份为 `user-config.md.bak-<时间戳>`
+  1. 先把你的配置备份为 `user-config.bak-<时间戳>.md`
   2. 交互三选一：`[1] 官方覆盖`（旧配置在备份中随时找回）/ `[2] 保留我的` + 官方版另存 `.upstream` 对照（默认）/ `[3] 稍后处理`（本次不生成对照文件）
   3. `--yes` 或非交互环境默认 `[2]`，最安全
 - **版本一致**：无感升级，只更新技能文件，配置原样保留

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.upstream.md` 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.upstream.md` 手动合并新配置点（如新增的 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

@@ -1,7 +1,6 @@
 ---
 name: magic-deck
-description: 把内容做成 HTML 形态、PPT 体验的魔法幻灯（单文件离线打开、零外部依赖）。内置播放引擎（自动播放/循环/间隔可设/从头或当前播放）、键盘热键（翻页/直达/截图/复制/全屏）、十七套内置模板（经典商务/极简留白/杂志画册/黑金发布/时间线叙事/流程步骤/海报宣传/复古报纸/金融报表/蓝图工程/教学板书/高管简报/扁平磁贴/模块网格/暗夜深色/自然清新/统计图表，放映时经「🎨 模板」面板随时切换
-+ 模板面板「💼 领域」Tab 二十二套成套模板（六分类：教育学术——毕业答辩/开题报告/教学课件；职场商务——年终汇报/竞聘述职/商业计划书/求职简历；企业运营——产品发布/科技发布会/营销方案/销售方案/企业培训/年会盛典；专业领域——金融分析/医疗科普/法律合规；党政政务——政务汇报/党建汇报；生活场景——餐饮品牌/旅游攻略/节日庆典/公益慈善，一键生成整套页面——封面+目录+内容页+图表页，两段确认可撤销）+ 图表动画五式（柱状生长/折线描画/饼图扇入/仪表扫弧/数字滚动，图表挂 data-anim-chart 翻页自动播放、翻回重放，保留图表自身动画）——可应用到全部页/仅本页/勾选页，支持「预览本页」先看效果再应用，标题自动映射到模板固定位置）、编辑能力（撤销/重做 Ctrl+Z、右侧页面管理边栏：缩略图跳页/新页/复页/排序/删页）+ 十七套主题面板即点即换（全部页/仅本页自由换肤）、动画库（右侧边栏「⚙ 工具」Tab：翻页风格八套 / 元素入场十二式 / 离场十二式 / 强调八式 / 标题文字动画四式，应用范围全部页面或仅本页，即点即换、选择记忆）、页内连接与外部链接、逐页 PNG 截图（本页/选页批量，选页面板默认全选=一键导出全部页）与本页/选页批量文字复制（均不含任何操作元素）、全屏放映纯净模式（无关元素自动退场）。当用户请求把内容做成幻灯片/PPT/演示文稿、生成 HTML 幻灯、做分享页/汇报页，提到 magic-deck 或 /magic-deck，或询问其用法（怎么用/使用说明/能干什么）时使用。用户要可编辑 .pptx 文件（导出 pptx、转成 PPT 文件）时不用本 skill（交给 deck-stage）；「做 PPT/演示文稿」未言明产出形态时先 AskUserQuestion 二选一（HTML 网页幻灯 → 本 skill；.pptx 可编辑文件 → deck-stage），不擅自默认。
+description: 把内容做成 HTML 形态、PPT 体验的魔法幻灯（单文件离线打开、零外部依赖）。内置播放引擎（自动播放/循环/间隔可设）、键盘热键（翻页/直达/截图/复制/全屏）、十七套内置布局模板与二十二套成套领域模板（六分类：教育学术/职场商务/企业运营/专业领域/党政政务/生活场景，一键生成整套页面）、图表动画五式（柱状生长/折线描画/饼图扇入/仪表扫弧/数字滚动）、编辑能力（撤销重做/页面管理边栏）、十七套主题面板即点即换、动画库（翻页风格八套/元素入场十二式/离场十二式/强调八式/标题动画四式）、页内连接与外部链接、逐页 PNG 截图与批量文字复制、全屏放映纯净模式。当用户请求把内容做成幻灯片/PPT/演示文稿、生成 HTML 幻灯、做分享页/汇报页，提到 magic-deck 或 /magic-deck，或询问其用法（怎么用/使用说明/能干什么）时使用。用户要可编辑 .pptx 文件（导出 pptx、转成 PPT 文件）时不用本 skill（交给 deck-stage）；「做 PPT/演示文稿」未言明产出形态时先 AskUserQuestion 二选一（HTML 网页幻灯 → 本 skill；.pptx 可编辑文件 → deck-stage），不擅自默认。
 allowed-tools: Bash, Read, Write
 disable-model-invocation: false
 ---
@@ -25,7 +24,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
 
 
@@ -41,7 +40,7 @@ disable-model-invocation: false
 
 ## ⚙️ 配置与自定义
 
-**执行本 skill 前必须先 Read 同目录 `user-config.md`**：默认配置（TEMPLATE/THEME/TRANSITION/ANIM/WIDTH/HEIGHT/SEC/FILENAME/DIR 等）与用户模板都在该文件中，以它为准。升级技能时 user-config.md 不会被覆盖，你的修改永久保留；官方更新配置时另存 `user-config.md.upstream` 对照文件，可按需手动合并新配置点。
+**执行本 skill 前必须先 Read 同目录 `user-config.md`**：默认配置（TEMPLATE/THEME/TRANSITION/ANIM/WIDTH/HEIGHT/SEC/FILENAME/DIR 等）与用户模板都在该文件中，以它为准。升级技能时 user-config.md 不会被覆盖，你的修改永久保留；官方更新配置时另存 `user-config.upstream.md` 对照文件，可按需手动合并新配置点。
 
 ## 规则速览
 
@@ -64,7 +63,7 @@ disable-model-invocation: false
 
 `user-config.md` 首行有 `CONFIG_VERSION` 字段，声明配置结构版本。本 skill 当前要求版本为 2。每次执行前先读 user-config.md：
 
-1. 若 CONFIG_VERSION 缺失或小于当前要求版本：先将旧 `user-config.md` 备份为 `user-config.md.bak-<时间戳>`
+1. 若 CONFIG_VERSION 缺失或小于当前要求版本：先将旧 `user-config.md` 备份为 `user-config.bak-<时间戳>.md`
 2. 按版本迁移规则迁移字段（新增字段补默认值、改名字段按映射改名、删除字段保留在备份并在对话中提示用户）
 3. 更新 `CONFIG_VERSION` 为当前版本
 4. 对话告知用户「配置已升级到 vN：新增 X、改名 Y」
@@ -73,7 +72,7 @@ disable-model-invocation: false
 
 **无法迁移项处理**（值域失效 / 语义漂移 / 数据不兼容）：三情形——①旧值不在新值域（如旧模板/主题名已移除）②同名键含义变化（单位/枚举变更）③数据文件 schema 不兼容。三绝不：绝不静默（无法迁移项停下问，不猜值）、绝不丢失（旧值永远在 .bak-时间戳）、一次说清（升级报告三段式：⚠️ 版本与备份路径 → ✅ 已自动迁移清单 → 🟡 无法迁移项逐条附原因+影响+建议替代）；随后 AskUserQuestion 三选项（A 用建议值 / B 用户给新值 / C 保持旧配置——不更新 CONFIG_VERSION，每次执行再提醒）；报告必附回滚一句话；数据文件迁移前先复制 .bak-时间戳，能映射则映射、不能则写兼容层或留备份提示手动整理
 
-升级技能时 user-config.md 不会被覆盖（官方更新另存 `user-config.md.upstream` 对照文件）。
+升级技能时 user-config.md 不会被覆盖（官方更新另存 `user-config.upstream.md` 对照文件）。
 
 ## 产物升级（回炉）
 
@@ -84,3 +83,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"]{