Community生产力与协作github.com

README编写器

编写或重写项目README,将访问者转化为用户和贡献者——包括一句话简介、徽章、60秒快速入门、真实示例、功能、常见问题、贡献指南和许可证——并能检查是否存在缺失章节、损坏的相对链接、目录锚点不匹配、缺失alt文本以及首个代码块位置过晚。当用户要求编写、改进、审查或重构README,或表示项目无人理解、无人加星时使用。

README编写器 是什么?

这个技能用于编写或重写项目README,其核心目标是在60秒内让访问者从“这是什么?”到成功运行第一个命令,然后展示如何进一步使用和如何做出贡献。该技能支持多种平台(如Claude Code、Cursor、Codex等),提供完整的流程指导:首先从代码中收集事实(如清单文件、CLI帮助、现有文档和许可证),询问用户无法从代码获取的信息(如目标受众、单一痛点和差异化优势),然后对现有README进行lint检查(基于Python脚本),接着按照指定的结构(标题+徽章、一句话简介、快速入门、功能、示例、配置、常见问题、路线图、贡献指南、许可证)编写或重写,并应用严格的编写规则(例如一句话简介不超过200字符、首个代码块在第60行之前、表格用于选项和比较、链接代替粘贴等)。lint规则涵盖标题、简介、徽章、安装、快速入门、代码块、滚动位置、贡献/许可证章节、常见问题、目录、alt文本、损坏链接、损坏锚点以及占位符等,并以适当退出码返回结果。该技能适用于编写新项目README、重写冗长或内容单薄的README、或项目发布前审查。不适用于API参考文档、长教程或架构文档。输出包括更新后的README.md(或diff摘要)、最终lint结果,以及未能验证的事实和需要用户填充的占位符列表。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/saizul/oss-maintainer-skills/tree/HEAD/skills/readme-writer

Installed? Explore more 生产力与协作 skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

README编写器 是做什么的?

README只有一个任务:在一分钟内让访问者从“这是什么?”到成功运行第一个命令,然后展示如何进一步使用和如何帮助。

何时使用

  • 为新项目编写README,或重写内容单薄或冗长的README
  • 在项目发布或1.0版本前审查README
  • 用户表示项目有访问量但没有加星、安装量或贡献者

何时不使用

  • API参考文档(从代码生成;在README中链接到它)
  • 长教程或架构文档:放在docs/目录并链接

工作流程

  1. 在编写前收集事实。 读取清单文件(pyproject.toml、package.json、composer.json、Cargo.toml...)、CLI的--help或主入口点、现有文档和许可证。找到真正的安装命令和真实的示例。永远不要发明标志、输出、基准测试或特性。

  2. 只向用户询问代码无法告诉你的信息: 项目的目标用户、它解决的单一问题、以及它为什么比明显的替代方案更好。如果用户无法提供,则从代码编写一个中立的简介,并标记以供审查。

  3. 检查当前README(如果有)。scripts/相对于此技能:

    python3 scripts/readme_lint.py README.md
    python3 scripts/readme_lint.py README.md --json --strict
    
  4. 按照structure.md中的结构编写,从模板开始。顺序很重要:标题+徽章、简介、(演示图片)、快速入门、功能、用法/示例、配置、常见问题、路线图、贡献指南、许可证。

  5. 应用编写规则:

    • 简介:一句话,不超过200个字符,不使用空泛的宣传词。模式:“<名称>是一个<类别>,它<做什么>为<受众>,<关键差异化>。”
    • 第一个代码块在第60行之前。每个命令必须可复制粘贴且真实。
    • 在命令后显示有用的输出(# => ...或单独的代码块)。
    • 使用表格表示选项和比较,使用列表表示功能(先说好处)。
    • 链接而不是粘贴:长文档、变更日志和API参考放在别处。
    • 每个图片都有alt文本;优先选择SVG或展示主要流程的短视频GIF。
  6. 徽章。 只使用真实且维护中的徽章,顺序如下:CI状态、最新版本(PyPI/npm/Packagist/release)、下载量(可选)、许可证。示例见structure.md。

  7. 重新lint 直到没有错误。解决警告,或告诉用户为什么无法解决。

  8. 检查lint无法检测的链接: 绝对URL和锚点。点击测试或说明哪些未经验证。

输出

  • 新的或更新的README.md(对于重写,显示差异摘要)。
  • 最终的lint结果。
  • 一个简短的列表,列出你无法验证的事实以及用户必须填充的占位符(演示GIF、截图、基准测试数据)。

Lint规则

规则级别含义
titleerror/warning恰好一个H1
pitcherror/warning标题下的一段简短简介
badgeswarning未找到徽章
installerror/warning安装(或快速入门)章节,包含代码块
quickstarterror/warning用法、快速入门或示例章节,包含代码
codeerror完全没有代码块
scrollwarning第一个代码块在--max-scroll行之后(默认60)
contributing, licensewarning缺失章节
faq, tocinfo建议添加
alt-textwarning图片没有alt文本
broken-linkerror相对链接指向缺失的文件,或空链接
broken-anchorerror#anchor链接(目录)不匹配任何标题或HTML id/name,使用GitHub的slug规则
placeholderwarning留有TODO、TBD或lorem ipsum

错误时退出码为1(带有--strict时警告也视为错误)。

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

相关技能