Skill Page Design Template

技能页面设计模板 / Skill Page Design Template

用途

把一个 WorkBuddy Skill 包装成可直接发布到 GitHub 的高质量展示页面。

输出两件东西：

1. README.md — GitHub 仓库主页，承担"第一印象 + 快速判断 + 完整导航"三重职责
2. SKILL.md frontmatter — WorkBuddy 平台加载时消费的元数据（展示名、描述、标签、路由）

设计哲学

一个 skill 页面上来就要回答三个问题：

• 这是什么（3 秒判断）
• 凭什么可信（来源纪律、版本记录、边界声明）
• 怎么用（触发场景、文件结构、加载策略）

别写行业通稿。给结构、给分层、给证据链。

工作流程

第一步：收集信息

向用户索取以下信息（缺啥问啥，别一次全问）：

🔴 CHECKPOINT · 收集完成后确认 展示收集到的信息，等用户确认后再进入生成阶段。若用户说"先做吧"，可跳过确认直接进入第二步。

第二步：生成 README.md

按 references/skill-page-template.md 的结构生成。每个章节的取舍见该模板内的 [必选] / [可选] 标注与「章节取舍指南」。

硬要求（32 项自检里会被机械判定的部分）：

• 必须有 | 项 | 内容 | 元数据表，且含 | **当前版本** | v{x.y.z} | 行
• 必须有 ## §0 三秒路由（或等价名）决策路由表
• 必须有不触发场景清单（≥3 条）与硬边界/免责声明
• 必须用 > ⚠️ 框出核心纪律
• 必须有 align=center 版权页脚
• 表格行占全文行数 ≥25%

🔴 CHECKPOINT · 生成后自检 生成完成后按 references/checklist.md 逐项核对。不通过项必须修复后才能交付。

第三步：生成 SKILL.md frontmatter

按 references/frontmatter-spec.md 的规范生成。注意平台字段长度上限：

⚠️ agent_created: true 要紧跟 description: 块之后。若在两者之间插入新字段，用 \nagent_created 作结束锚点的旧脚本会把后续字段一起算进 description 长度，报出假超标。

🔴 CHECKPOINT · 字段校验 逐项检查：四个展示字段是否齐全、长度是否超限、version 是否与 README 元数据表一致。

第四步：自检

交付前逐条核对 references/checklist.md 的 32 项。可执行版：

python scripts/check_page.py                    # 检查本 skill 自己
python scripts/check_page.py --path <skill目录>  # 检查任意 skill
python scripts/check_page.py --json             # 输出 JSON

退出码 0 = 无 FAIL，1 = 有 FAIL。脚本只判定能机械判定的项，判不了的标 SKIP 并说明原因——不假装通过。

第五步：核验目标 skill 自带的自检脚本（别跳，这一步抓过真问题）

跑完本模板的 32 项还不够——要确认目标 skill 自己的 validate_skill.py 是不是瞎的。

实测（2026-09-20，oilfield-well-kpi-advisor）：它自带自检脚本并报告"全部通过"，但该脚本的 frontmatter 检查只覆盖 name / description / version / agent_created 四个键——平台必填的四个展示字段全缺也照样全绿。同批另一个 skill 用了驼峰 displayName，同样没被发现。

必做三件事（详见 references/checklist.md 末节）：

1. 读它的自检脚本，确认平台四字段在检查范围内——不能只看它说"通过了"。
2. 确认 parse_frontmatter 处理块标量（旧实现把 description: | 解析成字面量 "|"，长度检查永远通过）。
3. 做反向测试：把 frontmatter 故意改回不合规，重跑自检，必须报错且退出码非 0。不报错的检查等于没有检查。

目标 skill 若没有自检脚本或不覆盖平台字段，在本轮一并补上——这是发布流程的一部分，不是额外需求。

🔴 CHECKPOINT · 交付前终检 交付前确认：五步全部走完、32 项自检有结论、SKIP 项已人工判定、版本四件套一致、目标 skill 自检脚本已做反向测试。

失败模式与兜底路径（if-then 三段式）

反模式与风险动作黑名单

反模式（生成时严禁）

1. ❌ 写行业通稿（"随着 XX 的发展"、"在 XX 的大背景下"）
2. ❌ 用散文代替表格（结构化信息必须用表格）
3. ❌ 模板与 SKILL.md 内容高度重复（模板只留骨架，细节在 references/ 里）
4. ❌ 跳过 CHECKPOINT 直接交付
5. ❌ 版本四件套不一致（SKILL.md / README / RELEASE-NOTES / git tag）
6. ❌ 硬边界不明确（只写"不替代 XX"，不写"→ 转 XX"）
7. ❌ 路由表有歧义（一个意图路由到多个章节）
8. ❌ 来源不可引用（"教材原话"落不到页码）

风险动作（绝对禁止）

1. 🚫 不给出"本 skill 适用于所有场景"的绝对结论
2. 🚫 不擅自修改用户 skill 的核心功能和用途
3. 🚫 不为了凑分数而添加冗余章节
4. 🚫 不静默跳过 CHECKPOINT
5. 🚫 不在同一上下文中自评自改

交付清单

完成后交付给用户：

1. README.md 完整内容（可直接写入仓库）
2. SKILL.md 的 frontmatter 片段（可直接合并）
3. 自检结果（32 项逐条结论）
4. 可选：RELEASE-NOTES.md 初始版本（如用户需要）
5. 可选：目录结构建议（是否需要 references/、scripts/、assets/）
6. 推送纪律：按 references/git-publish-safety.md 核验服务端真实状态后再推——重点是别覆盖别人已发布的历史（无共同祖先时用 commit-tree -p <远端HEAD> 造线性提交实现快进推送，不用 --force）
7. 要铺到多个 skill 时：按 references/rollout-across-skills.md 走——先扫全库找已定型的母本、先补海报文件再改 README、版本四件套（含 git tag）同号、目标 skill 没有 .git 时用临时克隆作业再同步回来