# Skill Page Design Template

> 为 WorkBuddy Skill 制作可直接发布到 GitHub 的高质量展示页面（README.md + SKILL.md frontmatter）。 五步工作流：① 收集信息（名称/定位/底本/知识规模/触发场景）；② 按 references/skill-page-template.md 生成 README 八节结构（元数据表、目标用户、内容分层、决策路由、来源纪律、文件结构、触发与不触发、版本记录）；③ 按 references/frontmatter-spec.md 生成平台必填展示字段；④ 按 references/checklist.md 逐条自检 32 项，可执行版为 scripts/check_page.py（27–32 为仓库与一致性：.gitattributes / RELEASE-NOTES / agent_created 位置 / description_zh 中文含量 / 相对链接 / SKILL↔README 版本对齐）；⑤ 核验目标 skill 自带的自检脚本是否真的覆盖平台字段（含反向测试）——实测踩过：某 skill 自检"全部通过"，实则平台四字段全缺。 何时调用：给 skill 做个页面、设计 skill 的 GitHub 展示、美化 skill 的 README、skill 发布页、skill 包装、skill 展示设计、skill page design、帮我写 README、skill 怎么包装。 不适用：纯代码开发、非 skill 类文档写作、公众号文章写作。

- Skill: `kwon85428-art/skill-page-design-template` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add kwon85428-art/skill-page-design-template`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kwon85428-art/skill-page-design-template/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: kwon85428-art (https://skillmd.com/u/kwon85428-art)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/kwon85428-art/skill-page-design-template

---


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

## 用途

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

输出两件东西：

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

## 设计哲学

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

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

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

---

## 工作流程

### 第一步：收集信息

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

| 必需 | 说明 |
|------|------|
| Skill 名称（中英文） | 展示名 + 英文翻译 |
| 一句话定位 | 这个 skill 干什么 |
| 底本/核心来源 | 基于什么教材/文档/API/方法论 |
| 知识规模 | SKILL.md 体量、references 数量与体积 |
| 触发场景 | 用户问了什么会激活 |

| 可选 | 说明 |
|------|------|
| 版本号 | 默认 v1.0.0 |
| 作者/版权 | 默认"老桂" |
| 相关链接 | 官网、讨论群等 |
| 测试集 | 有多少条用例、通过率 |
| 融合来源 | 是否合并了其他 skill |
| 特别纪律 | 有无引用分档、硬边界等 |

> **🔴 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` 的规范生成。注意平台字段长度上限：

| 字段 | 上限 | 性质 |
|---|---|---|
| `display_name_en` | 60 字符 | 平台硬限 |
| `description` | 1024 字符 | audit_skill.py 审计上限 |
| `description_zh` | 500 字符 | 平台硬限 |
| `description_en` | 1000 字符 | 平台硬限 |
| `display_name` | 建议 ≤20 字 | 无硬限 |

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

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

### 第四步：自检

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

```bash
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 三段式）

| 触发条件 | 一线修复 | 仍失败兜底 |
|---------|---------|-----------|
| 用户拒绝提供必需信息（如底本、触发场景） | 说明该信息对页面质量的影响，请求补充 | 基于已有信息生成，在 README 中标注"待补充"占位符 |
| 模板引用文件不存在（如 `references/skill-page-template.md` 缺失） | 检查路径是否正确，尝试从其他位置读取 | 按 SKILL.md 内的章节结构手动生成，不依赖外部模板 |
| 平台字段长度超限（`description_zh` > 500 字符） | 精简描述，删除触发词列表外的内容 | 只保留"何时用"核心触发词，删除示例和解释 |
| 用户要求"美化"但无具体方向 | 询问具体需求（视觉 / 结构 / 内容） | 按"结构优化 + 表格优先"两个维度默认处理 |
| README 与 SKILL.md frontmatter 版本号不一致 | 以 SKILL.md frontmatter 为准，同步更新 README | 以 README 为准，同步更新 frontmatter，并在 RELEASE-NOTES 记录 |
| 目标 skill 自检脚本"全部通过" | 读脚本确认平台四字段在检查范围内 | 视为未通过，按第五步补上并做反向测试 |
| 用户要求生成非 skill 类文档（纯代码 / PPT / 论文） | 说明本 skill 不适用，建议转交对应 skill | 终止流程，不强行生成 |

---

## 反模式与风险动作黑名单

### 反模式（生成时严禁）

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` 时用临时克隆作业再同步回来