自用 Skill 生成 / 审计工作台（skill-forge）
概述
本技能把「打磨 motor-design-advisor 技能（v1.7→v1.8→v1.9）」这一轮沉淀下来的方法论，固化为一套可复用的 skill 工厂。任何模式在需要新建、审计、迭代、打包一个 WorkBuddy skill 时，都能复用同一套经实战检验的约定：
- 解耦本地数据：技能包只放方法论 / 引擎 / 结构说明，不放具体项目数据；型号库、参数表等「本地数据」由【用户知识库】提供，
_resolve_index()稳健解析。 - 自包含打包：
scripts/内聚所有可执行引擎；不硬编码绝对路径；文件名全 ASCII（防 Linux/Docker 解压乱码）；用白名单 +.packignore打包，并断言「全 ASCII / 无缓存 / 不含本地数据」。 - 渐进式 references：SKILL.md 只留执行概览，详细知识、schema、清单放
references/，按需加载，不占主上下文。 - 自动化闸口：
selfcheck_template.py多段强检查 + 报告verify脚本，作为「可发布」的客观门槛。
知识分层（与光电系统总师专家一致）：
- 通用方法（主干）：内置 references/，保证广度与严谨。
- 项目实证（增强）：数据由知识库提供，不随包分发；技能仅内置 schema.json 说明结构。
- 标注纪律：实证值标 ✅；通用经验标 📌；不确定/限制标 ⚠️，缺失不臆造。
§0 三种工作模式 ↔ 入口
| 模式 | 触发意图 | 入口脚本 / 文档 |
|---|---|---|
| Forge（新建） | 从零搭一个 skill 骨架 | scripts/scaffold_skill.py |
| Audit（审计） | 拿审查文档/意见逐项核对并整改 | references/audit_checklist.md |
| Package（打包） | 打成可分发 ZIP + 跑自检 | scripts/pack_skill.py + scripts/selfcheck_template.py |
§1 Forge：新建一个 skill 骨架
运行脚手架生成标准骨架（含 SKILL.md 模板、references/、scripts/，并自动复制 pack_skill.py / selfcheck_template.py / .packignore）：
python scripts/scaffold_skill.py <skill_name> [--output <dir>] [--desc "一句话描述"]
<skill_name>必须 ASCII（连字符/下划线），这是 ZIP 不乱码的前提。- 默认
--output为~/.workbuddy/skills/（用户级，跨项目可用）。 - 生成后：填充
SKILL.md正文 → 写references/*.md（详细知识）→ 写scripts/*.py（确定性引擎）。
SKILL.md 写作纪律（详见 references/skill_anatomy.md）：
- frontmatter 必含 name / description / agent_created: true；description 用第三人称、写清「何时用、做什么、不适用什么」。
- 正文用命令式（动词开头），区分「已验证✅ / 通用经验📌 / 不确定⚠️」。
- 用 §0 工作流↔产物 表把步骤映射到产物；详细内容下沉到 references/。
§2 Audit：对照审查文档逐项核查（核心方法论）
拿到一份审查文档或主观意见后，不要照单全收，按 references/audit_checklist.md 的四步执行：
- 逐条核对：对每条发现，先用工具/读取确认「是否属实、在当前部署下是否构成问题」。
- 拆分优先级：落成 P0（阻断/必须）/ P1（重要工程逻辑）/ P2（健壮性/表述）三档。
- 区分采纳口径：
- 平台无关、确实有效 → 采纳并落实（如：ASCII 文件名、脚本打包、本地数据解耦、工程计算关口、描述收紧）。
- 部署专属（如针对 WeKnora 统一 Word 工具的建议） → 当前 WorkBuddy 无该工具，盲目采纳会破坏现有链路，显式不采纳并说明，或「保留实现层、仅移出可选格式文档」。 - 诚实标注未采纳项：在 evolution_log / 汇报中明确列出「未采纳 + 原因」，不假装全部完成。
整改后用 selfcheck_template.py 复跑，确保无回归。
§3 Package：自包含打包 + 自检闸口
3.1 打包
python scripts/pack_skill.py <skill_dir> [<output_zip>]
- 读取
<skill_dir>/.packignore（默认规则已覆盖__pycache__/*.pyc/*.zip/ 项目级可选文档）。 - 断言：① 包内文件名全 ASCII（否则中止，提示改名）；② 不含
__pycache__/*.pyc/.packignore；③ 不含本地数据（由.packignore排除项保证）。 - 失败
sys.exit(1)且不产出损坏包。
3.2 自检模板
复制 scripts/selfcheck_template.py 到目标技能，按实际资源改写顶部 CONFIG（文件清单、关键词、定位声明、是否解耦），运行：
python selfcheck_template.py
- 多段强检查（文件清单 / 解耦 / 引用一致性 / 关键词 / 定位声明 / 引擎可跑 / 产物校验）。
- 退出码
1= 存在问题，0= 全部通过。作为「可发布」的客观门槛。
3.3 引用资源
references/skill_anatomy.md— 一个优质 skill 的目录解剖（来自 motor-design-advisor 实证）。references/packaging_conventions.md— ASCII 文件名 / 自包含 / 本地数据解耦 /_resolve_index()模式。references/audit_checklist.md— 对照审查文档做 P0/P1/P2 自查的完整方法。references/selfcheck_pattern.md— 8 段强自检的结构模板。
§4 边界与反模式
- 反模式①：把 33 型本地数据塞进 skill 包 → 包臃肿、不可移植、ZIP 乱码。✅ 改为知识库提供 + schema 说明。
- 反模式②：脚本写死
D:/.../model_index.json绝对路径 → 换机器即崩。✅ 改为_resolve_index()（环境变量→向上查知识库→技能内置→优雅降级）。 - 反模式③：SKILL.md 堆满细节 → 主上下文爆炸。✅ 正文只留概览，细节下沉
references/。 - 反模式④：无自检直接发布 → 改坏不知。✅ selfcheck + verify 双闸口。
