davyzhong craft-readme Skill v2
目的：让 Agent 严格按照 readme-craft 方法论 v2.3 产出 95 分+ 的 README。
v2.1 升级：从 16 铁律扩展到 17 铁律（+T17 默认语言策略），反模式从 10 扩到 11，评分从 80 扩到 85，新增 LLM 友好测试 / a11y 工具扫描 / 包容性语言查改三道新检查。
何时调用
满足以下任一条件时触发：
- 用户说："帮我写 README"、"给这个项目生成 README"、"项目说明文档"
- 用户说："改造 README"、"升级 README"、"README 重写"
- 用户新建项目 / 新建工具 / 新建库，要求生成对应 README
- 用户明确指定引用本 Skill：
/load-skill craft-readme
不调用：
- 用户只想修复 README 中的某个 typo（用普通编辑能力即可）
- 用户在写非 README 的文档（CHANGELOG / CONTRIBUTING / API doc）
- 用户在审查别人的 README（用 code-review skill）
输入契约
调用 Skill 时，Agent 需要从用户或环境中获取以下信息：
| 字段 | 必填 | 来源 |
|---|---|---|
| 项目路径 | 必填 | 用户指定，或当前 working dir |
| 目标模板 | 推荐 | minimal / standard / rich / cn-academic，默认 standard |
| 语言 | 可选 | zh / en / both，默认跟随项目 |
| i18n 策略 | v2 新增 | mono（仅英文） / dual（中英） / multi（多语言） |
| 目标读者 | 推荐 | 用户画像（一句话） |
| 现截图 | 可选 | 路径列表（如 .github/screenshots/*.png） |
| Logo / 品牌色 | 可选 | emoji 或 SVG 路径 |
| 海外用户占比 | v2 新增 | none / <10% / 10-50% / >50%，影响 i18n 决策 |
如果必填信息不全，Agent 主动问 5-7 个问题补齐，不要假装知道。
工作流（Agent 必须按顺序执行）
Step 1 · 加载方法论 v2
# 读取核心方法论（v2 升级版）
cat /path/to/readme-craft/METHODOLOGY.md
# 重点读：5 条评估轴 + 19 条铁律 + 13 条反模式 + 95 分量表 + 同行对标
为什么先读方法论：避免 Skill 退化成"模板生成器"。Skill 的灵魂是 19 条铁律和 13 条反模式，不是某个具体模板。
Step 2 · 探查项目（自动）
ls -la <project_path>
cat <project_path>/pyproject.toml 2>/dev/null || cat <project_path>/package.json 2>/dev/null || cat <project_path>/Cargo.toml 2>/dev/null
cat <project_path>/README.md 2>/dev/null # 如果有旧版，先评估
find <project_path> -maxdepth 2 -type f \( -name "*.png" -o -name "*.jpg" -o -name "*.svg" -o -name "*.mp4" \) | head -20
# v2 新增：检查国际化痕迹
grep -r "README\.[a-z][a-z]\.md" <project_path> 2>/dev/null
# v2 新增：检查现有 badge
grep -E "img.shields.io|badge" <project_path>/README.md 2>/dev/null | head -10
收集信息：
- 项目名 / 一句话描述（看 README 或源码注释）
- 主要依赖（识别技术栈）
- 入口命令（看 setup.py / package.json / Cargo.toml）
- 现截图（看 .github/screenshots / docs/assets / 类似路径）
- 是否有 CONTRIBUTING / LICENSE / CODE_OF_CONDUCT / SECURITY
- v2 新增：海外用户占比（从 Discord / Issues / Star 来源判断）
- v2 新增：是否已有 i18n README
Step 3 · 选模板 + 选 i18n 策略（v2 升级）
按 METHODOLOGY.md §7 适用边界 决策：
项目类型 → 模板：
CLI 工具 / 小工具 → minimal 或 standard
GUI 桌面 / Web 应用 → rich
后端服务 / 框架 → standard
AI/ML 项目 → rich + 学术元素
中文知识库 / 方法论 → cn-academic
v2 新增 i18n 策略决策：
海外用户占比 < 10% → mono（仅英文，README.md）
海外用户占比 10-50% → dual（中英，README.md + README.zh.md）
海外用户占比 > 50% → multi（多语言，鼓励 PR 新增 README.<lang>.md）
不确定时：选 standard + dual（最普适）。
Step 4 · 缺失素材追问（必须 · v2 扩到 7 问）
读完项目后，向用户问 5-7 个问题，补齐关键决策：
v2 推荐问的 7 个问题（按优先级）：
1. 一句话讲清楚你的项目做什么、给谁用？[T2 价值主张]
2. 当前 stable 版本号是什么？许可证？[T3 badge]
3. 最推荐的安装/运行方式是什么？[T4 安装路径]
4. 有哪些截图/视频可以放到 README？[T6 视觉矩阵]
5. 谁在用 / 哪些场景？[T11 引用背书]
6. v2 新增：海外用户占比如何？[T13 i18n 策略]
7. v2 新增：项目有什么独特的技术亮点适合 LLM 引用？[T15 LLM 元数据]
不要超过 7 个问题（用户会烦）。如果素材充足可酌情减少。
Step 5 · 套模板 + 填内容（v2 新增关键动作）
读取 templates/<chosen>.md，把 Step 2 收集的信息填入对应章节。
关键动作：
- T1 视觉锤：如果用户没给 hero 图，用 mermaid 画一张架构图作为兜底；并提示用户后续替换
- T3 Badge 矩阵：用 shields.io 标准格式；v2 新增 security badge
- T4 安装：尽量给 5 路；至少有 macOS + Linux
- T5 Quickstart：v2 升级，Web / GUI 项目顶部加 Deploy/试用按钮
- T6 视觉矩阵：v2 升级，复杂项目补 1 段视频
- T7 卖点：必须 4-6 条；少于 4 条说明卖点没想清楚
- T8 Feature 分组：v2 升级，多模块项目补 T8b Ecosystem
- T12 收尾五件套：v2 升级，补 Code of Conduct + SECURITY.md 链接
- T13 i18n（v2 强制）：根据 Step 3 策略生成对应 README..md
- T14 包容性语言（v2 强制）：检查示例人名 / 默认指代
- T15 LLM 友好（v2 强制）：README 顶部加 YAML frontmatter
- T16 a11y（v2 强制）：检查所有图像 alt / 表格 header
Step 6 · 自检（v2 扩到 16 项）
读 checklist.md 18 条，逐项检查并标注 ✅ / ⚠️ / ❌。
v2 新增 3 道发版前检查：
1. LLM 友好测试：
在 ChatGPT / Claude 里问 5 个问题，看答案是否准确。
如果 LLM 答不全，回到 T15 修。
2. a11y 工具扫描：
npx pa11y https://github.com/your/repo#readme
如果 alt 缺失 / 表格无 header，回到 T16 修。
3. 包容性语言查改：
把 README 喂给 LLM，prompt："请指出不符合包容性语言的地方"
回到 T14 修。
自检输出格式（v2.3 95 分制）：
## ✅ 自检结果（craft-readme Skill v2.3 · 95 分制）
| 铁律 | 轴 | 状态 | 备注 |
|---|---|---|---|
| T1 视觉锤 | 视觉 | ⚠️ | 用了 mermaid 兜底，用户后续替换截图 |
| T2 三秒价值主张 | 内容 | ✅ | |
| T3 Badge 矩阵 | 内容 | ✅ | 5 个 badge，含 security |
| T4 安装 5 路齐发 | 结构 | ⚠️ | 只给了 macOS + Linux，缺 Windows/Docker |
| T5 30s 试用 + 60s Quickstart | 结构 | ✅ | 4 步复制即跑 |
| T6 视觉矩阵 | 视觉 | ❌ | 用户未提供截图，待补 |
| T7 卖点编号 | 内容 | ✅ | 5 条 |
| T8 Feature 分组 + Ecosystem | 视觉 | ✅ | 4 组 |
| T9 架构图 | 内容 | ✅ | mermaid 渲染 |
| T10 对照表 | 内容 | ⚠️ | 缺同类对比 |
| T11 引用背书 | 内容 | ❌ | 暂无用户引用 |
| T12 收尾五件套 | 结构 | ✅ | License + Contributing + CoC + Security + Roadmap |
| T13 i18n 规范 | 包容 | ✅ | dual 策略，主英文 README + README.zh.md |
| T14 包容性语言 | 包容 | ✅ | 用 they 单数，多元示例人名 |
| T15 LLM 友好元数据 | AI | ✅ | 顶部 YAML frontmatter，语义标题 |
| T16 无障碍 a11y | 包容 | ⚠️ | 大部分图像有 alt，缺视频 alt |
**评分**：56/80（合格，v2 标准开源水平，建议补 T6/T10/T11/T16 后再升正式版）
Step 7 · 输出（v2 新增 diff 摘要）
把生成的 README 写到 <project_path>/README.md（或用户指定路径）。
如果是 i18n 双语，再写 README.<lang>.md（v2 新增）。
如果是改造旧 README，输出 diff 摘要（v2 升级版）：
## 改造说明（v2.2 90 分制）
| 维度 | 旧版 | 新版 | 增量 |
|---|---|---|---|
| 铁律覆盖 | 8/12 | 16/16 | +8 |
| 反模式触发 | 4/8 | 0/10 | -4 |
| 评分 | 25/60 | 56/80 | +31 |
| i18n | ✗ | ✓ dual | 新增 |
| LLM 友好 | ✗ | ✓ | 新增 |
| a11y | ✗ | ✓ 部分 | 新增 |
输出契约
| 产物 | 路径 | 说明 |
|---|---|---|
| 新 README | <project_path>/README.md |
主要交付物 |
| i18n 版本（v2 新增） | <project_path>/README.<lang>.md |
视 Step 3 策略 |
| 自检结果 | 写在回复里 | 18 条逐项状态 + 90 分评分 |
| 评分 | 写在回复里 | 总分 + 评级 |
| 改造说明 | 写在回复里 | 如果是改造，列出主要 diff |
约束
硬约束（违反必须拒绝）
- 不能产出 0 图 README（除非用户明确说"只要文字版"）
- 不能伪造引用 — 用户 quote 必须真实可验证
- 不能产出含敏感信息的 README（密钥、token、内部 IP）
- 不能跳过自检 — 即使素材不全也要标注哪些 ⚠️/❌
- v2 新增：i18n 项目必须生成对应
README.<lang>.md，不能只放国旗链接 - v2 新增：所有图像必须有具体 alt 描述，不能是 "image" / "screenshot"
软约束（推荐遵守）
- 优先 mermaid 而非外链 SVG（避免死链）
- 优先 shields.io 而非手画 badge
- 安装命令必须真实可跑（不允许
pip install一笔带过，必须给具体包名） - 不要超过 33 国国旗链接（翻译泛滥）
- v2 新增：优先双语策略（
dual），不要直接 multi 让用户选择 - v2 新增：README 顶部必须加 YAML frontmatter，方便 LLM 引用
失败模式（v2 扩展）
| 场景 | 处理 |
|---|---|
| 用户说"随便写写" | 选 minimal 模板，3 段搞定 |
| 项目刚初始化无素材 | 强问 5-7 个关键问题，不假装知道 |
| 用户已有 README 要求改造 | 先评估打分（v2.2 90 分制），给出"哪些铁律违反 / 哪些保留"，再输出新版 |
| v2 新增：项目主要用户是海外 | 强制 i18n dual 策略，生成 README.md + README.zh.md |
| v2 新增：项目是 Web / SaaS 类 | 顶部加 Deploy 按钮（Netlify / Vercel / Cloudflare） |
| v2 新增：项目是 GUI 类 | 加 30-60 秒演示视频，无音频带字幕 |
| 跨语言项目（i18n） | 主 README 用 zh，README_en.md 翻译；不要堆 33 国国旗 |
| 中文项目想走国际 | 默认双语，主 README 英文，README_zh.md 中文 |
关联资源
METHODOLOGY.md— 18 条铁律详细定义（v2.2）checklist.md— 自检清单 18 条（v2.2 90 分制）templates/— 4 套模板examples/— before / after 案例对照
版本
- v2.3（当前）：19 铁律 + 13 反模式 + 95 分量表 + i18n / a11y / LLM / 默认语言 / 截图自动化 / CI 自愈 + 5 路集成
- v2.1（计划）：接 vhs/terminalizer 自动生成终端截图、Playwright 截 GUI
- v2.2（计划）：交互式自测（在线 60s 评分 + 模板推荐）
- v3.0（计划）：GitHub Action
readme-craft-botPR 自动评审