SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场readme-creator

readme-creator

写作与研究

查看项目

更新于 10-15 16:31

技能介绍

用途

README Creator 用于为“决定是否使用该项目的人”撰写或重写 README.md。它把 README 定位为项目的橱窗，而不是维基。读者通常来自搜索结果、注册表列表或个人主页，只有约十五秒时间，只关心一个问题：这值得我花时间吗？每一行要么回答这个问题，要么被删掉。

它明确不适用于：对已覆盖项目内容的 README 做文字润色；多页文档站点（应使用 docs-writing）；AGENTS.md 或 CLAUDE.md 这类智能体指令文件（应使用 agents-md）；修复 README 所描述的安装或首次运行体验（应使用 dx-audit）；落地页营销文案（应使用 copywriting）。

主要能力

  • 检测项目类型：技能包（skills/ 目录含 SKILL.md）、单体仓库（turbo.json、pnpm-workspace.yaml、workspaces 等）、CLI 工具（bin 字段、src/cli.* 或 commander/yargs/clap 依赖）、框架（插件/中间件架构、配置 API、扩展点）、库/包（main/exports 设置、无 bin、src/index.* 入口）、Web 应用（next.config.、vite.config. 等框架配置且不发布）。首个匹配的类型生效。
  • 判断 README 渲染位置：清单中 "private": true 或无注册表列表意味着仅 GitHub；已发布包还会渲染在 npmjs.com、PyPI 或 crates.io 上，这会影响图片 URL 并决定是否添加徽章。
  • 固定骨架：标题块（标题、标语、一行平实说明、注册表项目加徽章）、## Demo（仅有在线地址时）、## Install、## Quickstart、## License，中间插入两到四个能力章节。
  • 统一标题命名：使用 Install、Quickstart、Demo、License，而非 Installation、Getting Started、Quick start、Quick Start、Licence；全文使用句式大小写。
  • 受众把关：任何章节在写之前先问它帮助的是“决定使用项目的人”还是“修改项目的人”；贡献者内容移到 CONTRIBUTING.md 或 AGENTS.md，README 最多保留一行指引。
  • 写作规则：标题为带空格和大写的显示名并链接到在线站点；标语约 8 到 16 词，说明项目做什么而非是什么；第二行一句平实的话说明你实际用它做什么；安装命令取自清单 name 字段，只给一条最快命令；Quickstart 是最短但完整、能产生可见输出的示例，即使它成为文件中最长的块也保持完整；每个代码块复制粘贴后即可运行，不使用伪代码、占位导入或 foo、bar、my-app、your-name-here；长度按需，多数在 40 到 90 行，超过约 130 行应转为文档站点或 docs/ 文件夹。
  • 徽章：仅在项目已发布到注册表时添加，默认版本与许可证两个（技能包为安装量与许可证），统一风格与配色。
  • 验证：使用质量清单检查消费者路径与内部约定，并运行渲染检查（如 TODO/{{ 候选、em dash、遗留脚手架标题、相对图片路径等）。自动失败项包括缺少描述、缺少安装、残留样板、无法运行的代码示例或仅服务贡献者的章节。

使用方式

该技能以工作流形式运行，包含五个阶段：

  1. 阶段一：检测项目类型与渲染目标。读取清单（package.json、Cargo.toml、pyproject.toml、go.mod）中的 name、description、license、scripts、bin、"private"、repository；读取现有 README（若为重写）；扫描顶层布局。只向用户询问代码无法揭示的内容：这个项目解决什么问题（标语背后的“为什么”）、是否有要强制加入或排除的章节。若无法联系用户，则从清单和代码推断“为什么”，在总结中注明假设并继续。
  2. 阶段二：固定骨架，再选择能力章节。能力章节从 references/section-templates.md 的菜单中选两到四个，四个是上限。
  3. 阶段三：按模板撰写各章节。从 references/section-templates.md 复制每个章节的骨架，填充后应用该文件末尾的按类型说明。
  4. 阶段四：添加徽章。仅在阶段一发现注册表列表时进行，加载 references/badges-and-shields.md。
  5. 阶段五：验证。使用 references/quality-checklist.md 检查消费者路径与内部约定，报告可运行示例与链接/渲染结果。

参考文件：references/section-templates.md（阶段三：各骨架章节的标记、能力章节菜单、按类型说明）；references/badges-and-shields.md（阶段四：仅在阶段一发现注册表列表后）；references/quality-checklist.md（阶段五：完成前评分）。

语气：起草前检查外部 ghostwriter 技能是否存在配置文件 ${GHOSTWRITER_HOME:-~/.config/ghostwriter}/readme.md。存在时由它决定语域、拼写约定和任何内部风格标记，并与本技能冲突时以它为准。无配置文件时，默认使用简洁的第二人称祈使句、无 emoji、无感叹号，用具体数字而非形容词。

适用场景

  • 为项目撰写全新的 README。
  • 重写面向维护者而非消费者的 README（常见症状：第一个标题是 ## Workspaces，或安装步骤是 git clone）。
  • 需要统一一组仓库的 README 风格与结构。
  • 项目已发布到注册表，需要处理徽章与跨平台图片路径。

限制

  • 不适用于文字润色、多页文档站点、智能体指令文件、安装体验修复或落地页营销文案。
  • 单体仓库本身不是 README 的项目类型，而是交付机制；应针对陌生人实际安装或访问的内容撰写。
  • 若两种类型仍同时适用，选择多数用户的消费方式，将次要角色折叠为一个额外章节。
  • 重写已发布包的 README 时，npmjs.com 和 PyPI 显示的是上次发布时的 README，页面只在下次发布后更新。
  • 相对图片路径在 GitHub 上可渲染，但在 npmjs.com 和 PyPI 上会 404；已发布包需指向 raw.githubusercontent.com 的绝对地址。
  • 外部图片托管会失效，建议将图片提交到 .github/assets/ 下。
  • 深色/浅色 logo 使用 <picture> 与两个 <source media> 及 <img> 回退；#gh-dark-mode-only URL 片段已弃用；PyPI 会剥离 <source> 只显示回退，因此回退应为浅色版本。

  • [!NOTE] 等提示在 GitHub、npmjs.com 和 crates.io 上渲染，PyPI 会显示字面量 [!NOTE]；每个 README 最多一个，仅用于会破坏安装的事项。

  • https://img.shields.io/github/license/{owner}/{repo} 读取仓库检测到的许可证；无 LICENSE 文件时会渲染 license: not identified，比没有徽章更糟，添加前需确认文件存在。
  • 不要发布默认脚手架 README（create-next-app、create-vite），应整体替换。
  • 功能列表使用 - Name: what it does. 带冒号；带空格的连字符写法不符合内部风格。
  • 重述标语的功能章节是噪音，应按读者获得的内容命名。

相关技能

  • README 已存在且需要文字审计，或需要完整文档站点：docs-writing。
  • 项目需要智能体指令（AGENTS.md、CLAUDE.md），包括受众把关移出的内容：agents-md。
  • README 所记录的安装或首次运行路径本身有问题：dx-audit。
  • 标语之外的落地页或营销文案：copywriting。
  • 以用户自己的语气起草：外部 ghostwriter 技能（若已安装）、平台 readme。

维护说明：evals/evals.json 包含本技能变更的回归场景，不在用户任务期间加载。