skill-forge-hub 1.0.5 → 1.0.6

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 SkillForge（技能锻造坊）npm 包 `skill-forge-hub`（命令名 `skill-forge`）版本变更记录。
 
+## 1.0.6（2026-11-12）
+
+**meta-forge 规范与模板对齐：三大实战教训入规 + template 模板现代化**
+
+- template/ 模板对齐 forge-rules 新规范：SKILL.md 重写（第 0 步读 user-config、配置版本机制节、产物升级回炉节（条件）、文档同步自检纪律节、交付自检硬门禁）；新增 template/user-config.md（CONFIG_VERSION: 1 + 保护声明）与 template/resources/usage-guide.md（咨询应答模板）；README 拆掉「配置必须留在 SKILL.md」旧句改为配置出站
+- forge-rules 机制三补入场动画兜底：reference.html 含滚动入场动画（IntersectionObserver + JS 门控）必须带 2s 兜底 setTimeout 强制全显——IO 不触发的环境（headless 截图/打印预览/PDF 导出/嵌入式 webview）卡片不得永久隐藏（meeting-minutes 1.0.5 空白截图教训入规）
+- forge-rules 机制六补页面执行层自愈：id meta 非法/缺失时按路径键（sf-heal: + pathname）自愈为标准 UUID v4 并回写 meta、console.warn 报警——执行层第三防线入规
+- forge-rules 机制八补用户数据类细则：深升级重建必须沿用原页稳定 ID meta 值（换 ID = 数据失联），数据文件一概不动
+- 验证环扩充：静态门禁加第 13 项（入场动画兜底检查）；运行时实测加第 4 项（headless 截图验证内容完整，截图空白即失败）
+- meta-forge 自身对齐：SKILL.md description/流程第 3 步/规则速览补 preserve 保护清单与机制条件（含 HTML 加机制三七八、localStorage 记忆加六、半定制资产加五）；usage-guide 机制清单对齐 forge-rules 八项编号；user-config.md 修复 CONFIG_VERSION 行尾注释吞掉 DIR 行的换行 bug
+
 ## 1.0.5（2026-11-12）
 
 **月报技能上线：monthly-report + 报表家族四选一分流 + 登台月报映射**

package/meta-forge/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: meta-forge
-description: 锻造新技能的元技能（造 skill 的 skill）。按 SkillForge 工坊规范从需求出发生成完整技能包（薄入口 SKILL.md + 按阶段拆分的 resources/ + 用户配置 user-config.md），自动植入机制体系：CONFIG_VERSION 配置版本钥匙、user-config 配置抽离、reference 双轨（含 HTML 输出时）、多文件隔离（页面有 localStorage 记忆时）、零侵权脱敏离线纪律（含 HTML 输出时）、产物升级回炉（含 HTML 输出时）、文档同步自检纪律；技能入 SkillForge 仓库时同步登记 README 分类表与 cli.js CATEGORIES。当用户请求创建新技能、造一个 skill、做一个 XX 技能、把 XX 流程固化成技能，或询问 meta-forge 用法（怎么造技能/元锻炉怎么用）时使用。
+description: 锻造新技能的元技能（造 skill 的 skill）。按 SkillForge 工坊规范从需求出发生成完整技能包（薄入口 SKILL.md + 按阶段拆分的 resources/ + 用户配置 user-config.md），自动植入机制体系：CONFIG_VERSION 配置版本钥匙、user-config 配置抽离、reference 双轨（含 HTML 输出时）、多文件隔离（页面有 localStorage 记忆时）、零侵权脱敏离线纪律（含 HTML 输出时）、产物升级回炉（含 HTML 输出时）、preserve 保护清单（含半定制资产时）、文档同步自检纪律；技能入 SkillForge 仓库时同步登记 README 分类表与 cli.js CATEGORIES。当用户请求创建新技能、造一个 skill、做一个 XX 技能、把 XX 流程固化成技能，或询问 meta-forge 用法（怎么造技能/元锻炉怎么用）时使用。
 allowed-tools: Bash, Read, Write
 disable-model-invocation: false
 ---
@@ -14,7 +14,7 @@ disable-model-invocation: false
 0. **读用户配置**（DIR/REGISTER/CONFIG_VERSION）→ 先 Read 同目录 `user-config.md`
 1. **需求澄清**（技能名、触发场景、产出形态、可配置项、是否含 HTML 输出、是否入仓库）→ 读 `resources/forge-rules.md` 的「一、澄清清单」
 2. **结构生成**（薄入口 + resources 拆分 + 咨询应答接线）→ 读 `resources/forge-rules.md` 的「二、结构规范」
-3. **机制植入**（CONFIG_VERSION 钥匙 / user-config 抽离 / reference 双轨 / 多文件隔离 / 零侵权脱敏离线 / 产物升级回炉 / 自检纪律，缺一不可；含 HTML 输出加机制六、七、八）→ 读 `resources/forge-rules.md` 的「三、机制体系」
+3. **机制植入**（CONFIG_VERSION 钥匙 / user-config 抽离 / reference 双轨 / 多文件隔离 / 零侵权脱敏离线 / 产物升级回炉 / preserve 保护清单 / 自检纪律，缺一不可；含 HTML 输出加机制三、七、八，页面有 localStorage 记忆加机制六，含半定制资产加机制五）→ 读 `resources/forge-rules.md` 的「三、机制体系」
 4. **验证环**（静态门禁 grep 逐项 + 含 HTML 时 Playwright 运行时实测：零 JS 错误 / 键带路径 / 刷新恢复 / 多文件隔离 + 交付报告附验证证据，任一未过修复重跑禁止跳过）→ 读 `resources/forge-rules.md` 的「四、验证环」
 5. **仓库登记**（技能入 SkillForge 仓库时：README 技能分类表/技能清单/目录结构 + cli.js CATEGORIES 同步登记，登记后跑 `skill-forge ls` 验证）→ 读 `resources/forge-rules.md` 的「五、仓库登记」
 6. **使用咨询**（用户只问「怎么造技能」等用法、未要求创建）→ 读 `resources/usage-guide.md`，将其内容原样输出（首行标题改为「元锻炉使用指南」），不创建任何文件
@@ -42,7 +42,7 @@ disable-model-invocation: false
 
 ## 规则速览
 
-- 机制体系缺一不可：CONFIG_VERSION 钥匙（配置版本机制节 + user-config 配置块首行 CONFIG_VERSION: 1）、user-config 抽离（用户可改配置全部出站，SKILL.md 只引用不内嵌）、reference 双轨（含 HTML 输出的技能以 reference.html 为样式真相源）、多文件隔离（页面有 localStorage 记忆时键带路径命名空间）、零侵权脱敏离线（品牌字体零出现、禁 CDN 离线可开、示例数据零真实身份）、产物升级回炉（HTML 带模板版本戳、业务/数据格式/页面改动均 bump、旧产物可交互回炉、生成时顺扫旧版主动提示）、自检纪律（改一处 grep 全仓）
+- 机制体系缺一不可：CONFIG_VERSION 钥匙（配置版本机制节 + user-config 配置块首行 CONFIG_VERSION: 1）、user-config 抽离（用户可改配置全部出站，SKILL.md 只引用不内嵌）、reference 双轨（含 HTML 输出的技能以 reference.html 为样式真相源）、多文件隔离（页面有 localStorage 记忆时键带路径命名空间）、零侵权脱敏离线（品牌字体零出现、禁 CDN 离线可开、示例数据零真实身份）、产物升级回炉（HTML 带模板版本戳、业务/数据格式/页面改动均 bump、旧产物可交互回炉、生成时顺扫旧版主动提示）、preserve 保护清单（半定制资产 .preserve 声明、CLI 升级永不覆盖、官方更新另存 .upstream 对照）、自检纪律（改一处 grep 全仓）
 - 薄入口：SKILL.md 只留 frontmatter / 生成流程 / 配置节 / 机制节 / 规则速览；重内容按阶段拆 resources/，一文件一职责
 - 新技能必须带 user-config.md（含 CONFIG_VERSION: 1）与 resources/usage-guide.md（咨询应答原样输出源）
 - 完整规则（澄清清单 / 结构规范 / 机制体系 / 验证环 / 仓库登记）见 `resources/forge-rules.md`

package/meta-forge/resources/forge-rules.md

@@ -52,6 +52,7 @@
 - 生成 HTML 必须先 Read reference.html 与样式文档两份，以 reference.html 为骨架模板逐处替换数据
 - 修改 HTML 效果必须同步更新 reference.html + 样式文档描述，禁止只改一处；改完互相 grep 关键参数确认对齐
 - 铁律写入样式文档首段：「Reference 铁律（最高优先）」
+- 入场动画兜底：reference.html 含滚动入场动画（IntersectionObserver + JS 门控初始隐藏）时，脚本必须带 2s 兜底 setTimeout 强制全显（`.rv:not(.in)` 模式或等价代码）——IO 不触发的环境（headless 截图 / 打印预览 / PDF 导出 / 嵌入式 webview）卡片不得永久隐藏
 
 ### 机制四：文档同步自检纪律
 
@@ -73,6 +74,7 @@
 - **绝对禁止「固定键最近快照兜底」双键模式**：固定键在 file:// 同源下全局共享，A 写快照 B 兜底读到 → 必然串台（真实教训：prompt-pouch 曾因此 B 份继承 A 份分组/收藏，报障后改内嵌 ID）
 - 旧版数据迁移桥：新 ID 键读不到时一次性读旧版路径键（`旧前缀:路径-键`）迁入 ID 键；旧固定键/旧固定库数据归属不明，禁止迁入
 - 命名空间变量声明位置 = 所有使用它的代码块的**公共作用域**：页面含多个独立 `<script>`/IIFE 时，每个作用域各自声明（IIFE 内的 var 是局部变量，IIFE 外够不到；引用不可见会 ReferenceError、被 catch 静默吞掉 → 机制静默失效）
+- 页面执行层自愈：HTML 内嵌 JS 启动时校验 id meta——非法或缺失（占位残留 / 手写变体 / 误沿用旧值）时按路径键（`'sf-heal:' + location.pathname`）自愈为 crypto.randomUUID() 标准 v4 并回写 meta，console.warn 显性报警；路径键持久化保证同文件跨打开稳定复用（避免每次打开换新键丢记忆）；合法 UUID 原样放行（复制文件副本 = 同一身份共享数据，是特性）
 
 ### 机制七：零侵权、脱敏与离线纪律（HTML 产出技能必植入）
 
@@ -86,6 +88,7 @@
 - 产物版本戳：生成 HTML 时头部写 `<meta name="sf-template" content="<技能名>@N">`（N 为模板版本，初版 1）；模板升级时递增 N 并同步 reference.html 与 SKILL.md「产物升级（回炉）」节；检测双标记：版本戳 + 稳定 ID meta——无版本戳或缺少 `<前缀>-id` meta 的产物一律视为 v0 最旧版，必须进升级清单
 - 数据真相源：md/txt 与 html 同落盘，md 全文为内容底稿，html 永远可从 md 重建
 - 两级升级：浅升级（CSS/JS 变化、DOM 结构不变）→ 对旧页替换 <style> 块与交互脚本、正文原样保留；深升级（DOM 结构变化）→ 从同目录 md 底稿重生成，先备份旧版 .bak-时间戳
+- 用户数据类细则（IndexedDB 数据按稳定 ID 命名空间存取的技能）：深升级重建必须沿用原页稳定 ID meta 值（换 ID = 数据失联，重建后原收藏/分组照旧读回）；<DATA_DIR> 数据文件一概不动
 - 回炉交互：用户说「升级旧产物/回炉」→ 扫落盘目录读版本戳筛旧版（无版本戳或缺少稳定 ID meta 的产物视为 v0 最旧版，一并进清单） → 列清单（文件/旧版本/手改状态：旧 html 正文与 md 正文对比，不一致视为可能手改）→ AskUserQuestion 选全部或部分 → 逐份升级 → 报告三段式（✅ 已升级 / ⚠️ 手改保留 / 🟡 失败项原因）
 - 版本递增判定：模板业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与 SKILL.md「产物升级（回炉）」节；纯措辞润色不 bump
 - 主动提示：每次生成 HTML 或用户使用该技能 HTML 产出时，顺扫落盘目录读版本戳；发现低于当前模板版本的旧产物，主动告知「技能模板已升级至 vN，检测到 X 份旧版产物（vN-1），说『把我旧XX都升级成新样式』即可一键升级」，不让用户背触发语
@@ -106,12 +109,14 @@
 10. 示例数据脱敏：全文 grep 无真实项目名/人名/公司名/平台名/本机路径（/Users/具体用户名、~/SmartDeveloper 等）；页脚署名 GENERATED BY AI TEAM
 11. 产物版本戳（含 HTML 的技能）：reference.html 头部含 `<meta name="sf-template" content="<技能名>@N">`（N≥1）；SKILL.md 含「产物升级（回炉）」节且判定含无版本戳/无稳定 ID meta 视为 v0 最旧版
 12. 版本递增与主动提示（含 HTML 的技能）：SKILL.md 回炉节含版本递增判定（业务/数据格式/页面改动均 bump）与主动提示语（顺扫旧产物 + 告知触发语）
+13. 入场动画兜底（含 HTML 且含滚动入场动画的技能）：reference.html 含 2s 兜底强制全显代码（`.rv:not(.in)` 模式或等价），确保 headless 截图 / 打印预览内容全显
 
 ### B. 运行时实测（含 HTML 的技能必做，Playwright headless channel="chrome"）
 
 1. 页面加载零 JS 错误（pageerror 监听 + 控制台检查）
 2. 关键交互实测：主题/状态切换 → localStorage 键带路径 → 刷新恢复
 3. 多文件隔离实测：复制 HTML 到第二路径（用户数据类改成换 ID）→ 两份各自读写键互不干扰；用户数据类加测：同 ID 文件移动到新目录 → 数据保留
+4. 截图验证：headless 全页截图内容完整（标题 / 关键卡片 / 区块可见），入场动画兜底后内容全显；截图空白即失败（真实教训：入场动画无兜底 → headless 截图空白）
 
 ### C. 验证证据（交付报告必附）
 

package/meta-forge/resources/usage-guide.md

@@ -10,10 +10,11 @@ meta-forge 是「造 skill 的 skill」：把一段重复劳作，按 SkillForge
   1. CONFIG_VERSION 钥匙——配置结构带版本号，升级时自动备份迁移，不丢用户设置
   2. user-config 抽离——用户可改配置全部出站到 user-config.md，升级永不覆盖
   3. reference 双轨——技能含 HTML 输出时，reference.html 是定稿样式真相源，改样式三处同步
-  4. 多文件隔离——页面有 localStorage 记忆时，键按页内嵌唯一 ID 命名空间，多份产物互不串台、改名/移动目录记忆不丢
-  5. 零侵权脱敏离线——品牌字体零出现、禁 CDN 页面离线可开、示例数据零真实身份（通用占位）
-  6. 自检纪律——改任一文件 grep 全仓核对关键词，旧词零残留
-  7. 产物升级回炉——HTML 带模板版本戳（业务/数据格式/页面改动均 bump），升级后可扫旧产物交互式回炉（浅升级区块替换/深升级 md 重建），生成时顺扫旧版主动提示触发语
+  4. 自检纪律——改任一文件 grep 全仓核对关键词，旧词零残留
+  5. preserve 保护清单——含半定制资产（设计系统/模板底稿）时 .preserve 声明，CLI 升级永不覆盖，官方更新另存 .upstream 对照
+  6. 多文件隔离——页面有 localStorage 记忆时，键按页内嵌唯一 ID（标准 UUID v4）命名空间，多份产物互不串台、改名/移动目录记忆不丢
+  7. 零侵权脱敏离线——品牌字体零出现、禁 CDN 页面离线可开、示例数据零真实身份（通用占位）
+  8. 产物升级回炉——HTML 带模板版本戳（业务/数据格式/页面改动均 bump），升级后可扫旧产物交互式回炉（浅升级区块替换/深升级 md 重建），生成时顺扫旧版主动提示触发语
 - 交付前跑验证环（偏差必被发现）：静态门禁逐项 grep + 含 HTML 时 Playwright 实测（零 JS 错误 / 键带路径 / 刷新恢复 / 多文件隔离），验证证据随交付报告附上
 - 技能入 SkillForge 仓库时，自动登记 README 技能分类表/技能清单/目录结构与 cli.js CATEGORIES
 

package/meta-forge/user-config.md

@@ -9,7 +9,8 @@
 ## ⚙️ 默认配置（用户可手动修改；临时口头要求永远优先）
 
 ```yaml
-CONFIG_VERSION: 1              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）DIR: auto                      # 新技能生成目录：auto = 探测 SkillForge 仓库根（~/SkillForge 或含 cli.js 的当前目录）；也可写死绝对路径
+CONFIG_VERSION: 1              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
+DIR: auto                      # 新技能生成目录：auto = 探测 SkillForge 仓库根（~/SkillForge 或含 cli.js 的当前目录）；也可写死绝对路径
 REGISTER: true                 # 仓库登记：true = 生成后自动更新 README 技能分类表/技能清单与 cli.js CATEGORIES；false = 只生成技能包不登记
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-forge-hub",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "SkillForge (技能锻造坊) — a curated collection of AI craft skills. Install once, then pick skills interactively: daily/weekly/monthly/quarterly/annual reports, meeting minutes, article-to-HTML, magic-deck slides, deck-stage PPTX, prompt-pouch manager, Pandoc doc converters, meta-forge.",
   "bin": {
     "skill-forge": "cli.js"

package/template/SKILL.md

@@ -11,31 +11,35 @@ disable-model-invocation: false
 
 ## 生成流程
 
+0. **读用户配置**（<配置项列表，如 DISK/DIR/TEMPLATE>）→ 先 Read 同目录 `user-config.md`
 1. **阶段一（做什么）** → 读 `resources/xxx.md`
 2. **阶段二（做什么）** → 读 `resources/yyy.md`
 3. **阶段三（做什么）** → 读 `resources/zzz.md`
-3.5 **交付前自检**（落盘前必做，硬门禁不可跳过）：<按技能类型写自检手段——页面类 用 Playwright headless 零报错（channel="chrome"）+ localStorage 键路径命名空间 核验（固定键零残留）+ 多文件隔离实测（复制 HTML 到第二路径互不干扰）+ 品牌字体 零侵权扫描（PingFang/YaHei/apple-system 等零出现）+ 示例数据脱敏核验（真实项目名/人名/公司名/本机路径零出现，署名 GENERATED BY AI TEAM）+ 产物版本戳核验（`<meta name="sf-template" content="<skill>@N">` 已写入且 N 与当前模板版本一致；业务/数据格式/页面改动必 bump 版本）；文档类检查结构与数据纪律； 产物类校验文件完整性与内容一致>——未通过修复后重跑，禁止跳过直接交付
+3.5 **交付前自检**（落盘前必做，硬门禁不可跳过）：<按技能类型写自检手段——页面类用 Playwright headless 零报错（channel="chrome"）+ localStorage 键路径命名空间核验（固定键零残留）+ 多文件隔离实测（复制 HTML 到第二路径互不干扰）+ 品牌字体零侵权扫描（PingFang/YaHei/apple-system 等零出现）+ 示例数据脱敏核验（真实项目名/人名/公司名/本机路径零出现，署名 GENERATED BY AI TEAM）+ 产物版本戳核验（`<meta name="sf-template" content="<skill>@N">` 已写入且 N 与当前模板版本一致；业务/数据格式/页面改动必 bump 版本）；文档类检查结构与数据纪律；产物类校验文件完整性与内容一致>——未通过修复后重跑，禁止跳过直接交付
 4. **使用咨询**（用户只问用法、未要求生成）→ 读 `resources/usage-guide.md` 原样输出（首行标题改为「XX使用指南」），不执行任何生成动作
 
-## ⚙️ 默认配置（用户可手动修改；临时口头要求永远优先）
+## ⚙️ 配置与自定义
 
-```yaml
-DISK: true      # 示例配置项：是否落盘写文件；false = 默认只在对话输出
-DIR: auto       # 示例配置项：落盘根目录
-```
+**执行本 skill 前必须先 Read 同目录 `user-config.md`**：默认配置（<配置项列表>）与自定义模板都在该文件中，以它为准。升级技能时 user-config.md 不会被覆盖，你的修改永久保留；官方更新配置时另存 `user-config.md.upstream` 对照文件，可按需手动合并新配置点。
 
-> 临时口头要求（仅对当次生效，不修改上方配置）：说「xxx」→ 当次改某行为；……
+## 配置版本机制（升级保护）
 
-## 📝 自定义模板（TEMPLATE: custom 时启用，用户可手改）
+本 skill 当前配置版本为 `1`（对应 user-config.md 中的 `CONFIG_VERSION`）。执行时若发现 user-config.md 的 CONFIG_VERSION 与本节声明的当前版本不一致：
 
-把顶部 TEMPLATE 改为 custom 后，按下面结构生成（段名、段数、条目格式均可改）：
+1. 先将旧 user-config.md 备份为 `user-config.md.bak-<时间戳>`（同目录，绝不删除旧值）
+2. 按本节「配置升级规则」迁移字段：新增字段补默认值、改名字段按映射改写、删除字段的值保留在备份中并在对话提示用户手动确认
+3. 更新 CONFIG_VERSION 为当前版本
+4. 对话中明确告知用户「检测到配置版本从 X 升级到 Y，旧配置已备份至 <路径>」
 
-```text
-段一：……（每条：……）
-段二：……（每条：……）
-```
+升级本 skill 时，配置结构如有变化必须同步更新本节的当前版本号与迁移说明；禁止在未声明版本变更的情况下静默修改配置语义。
 
-> 只写段结构与条目格式即可；未写明的细节沿用默认规范。
+## 产物升级（回炉）——仅含 HTML 输出的技能保留本节，否则删除
+
+生成 HTML 时头部写版本戳 `<meta name="sf-template" content="<skill>@1">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧产物/回炉旧页面/旧XX换新样式」时：扫落盘目录读版本戳筛出旧版（无版本戳或缺少稳定 ID meta 的产物视为 v0 最旧版，一并进清单）→ 列清单（文件/旧版本/手改状态）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文原样保留；深升级（DOM 结构变化）从同目录 md 底稿按当前 reference.html 重建且**沿用原页稳定 ID meta 值**（用户数据类换 ID = 数据失联），先备份旧版 `.bak-时间戳` → 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物主动告知「技能模板已升级至 vN，检测到 X 份旧版产物，说『把我旧XX都升级成新样式』即可一键升级」，不让用户背触发语。
+
+## 文档同步自检纪律（维护者必读）
+
+修改本 skill 任一文件（SKILL.md / user-config.md / resources/*）后，必须 grep 全文核对相关关键词在各文件间一致（如机制名/流程节点/字段名改名时新旧词全仓核对，旧词零残留才算完成）。
 
 ## 规则速览
 

package/template/resources/README.md

@@ -16,5 +16,5 @@
 约定：
 
 - 每份 resource 独立可读，不互相引用（避免读取链断裂）
-- 用户可手改的配置（默认配置 / 自定义模板）必须留在 SKILL.md，不进 resources
+- 用户可手改的配置（默认配置 / 自定义模板）全部进 user-config.md，SKILL.md 只在第 0 步引用，不内嵌配置值
 - resource 内标题用原章节标题，内容从旧版单文件 SKILL.md 原样迁移

package/template/resources/usage-guide.md

@@ -0,0 +1,17 @@
+# <技能名>使用指南
+
+<一句话介绍：做什么、一句话触发示例>
+
+## 能干什么
+
+- <能力 1>
+- <能力 2>
+
+## 怎么用
+
+- 「<触发语 1>」→ <产出 1>
+- 「<触发语 2>」→ <产出 2>
+
+## 常见问题
+
+- <高频问题>：<答案>

package/template/user-config.md

@@ -0,0 +1,28 @@
+# 用户配置（升级技能时本文件不会被覆盖）
+
+> 你的个人配置全放在这里。skill-forge 升级技能时官方只更新 SKILL.md 与 resources/，
+> 本文件始终保留你的版本——落盘目录、格式开关放心改。
+> 官方升级若带来新配置点，会另存 `user-config.md.upstream` 对照文件到同目录，
+> 你按需查看并手动合并新配置点到本文件。
+
+## ⚙️ 默认配置（用户可手动修改；临时口头要求永远优先）
+
+```yaml
+CONFIG_VERSION: 1              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
+DISK: true                     # 示例配置项：是否落盘写文件；false = 默认只在对话输出
+DIR: auto                      # 示例配置项：落盘根目录
+TEMPLATE: default              # 示例配置项：模板开关（default 默认模板 / custom 自定义模板）
+```
+
+> 临时口头要求（仅对当次生效，不修改上方配置）：说「xxx」→ 当次改某行为；……
+
+## 📝 自定义模板（TEMPLATE: custom 时启用，用户可手改）
+
+把 TEMPLATE 改为 custom 后，按下面结构生成（段名、段数、条目格式均可改）：
+
+```text
+段一：……（每条：……）
+段二：……（每条：……）
+```
+
+> 只写段结构与条目格式即可；未写明的细节沿用默认规范。