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

openclaw-readme-standard

写作与研究

查看项目

更新于 10-16 04:05

技能介绍

用途

这是一个 README 写作与审校技能，用于统一 steipete 和 openclaw 组织下所有公开 README 的结构。在撰写或审阅 README 之前加载此技能。参考实现是 openclaw/fs-safe，如果不确定“好”的标准是什么，可以先阅读它的 README。

核心结构

每份 README 都应依次回答以下问题，不绕弯：

  1. 这是什么？—— 一句陌生人也能看懂的话。
  2. 我怎么使用它？—— 最小的真实安装步骤，以及能证明卖点的快速开始。
  3. 逐步增加复杂度 —— 每个部分都假设读者已读过上一部分；深度参考资料移到 docs/（或文档站点）并以链接方式引用。

具体骨架：

# <名称> <一个 emoji> — <俏皮标语，一行>

<徽章行>

<1–2 句克制的话：它是什么、面向谁。不要用形容词去承担名词该做的事。>

<可选：一段 ≤10 行的小型代码/终端示例，展示核心价值。>

## Install          ← 先给最小路径（brew/npm/npx），替代方式放后面
## Quick start      ← 60 秒内首次成功；命令必须真的能运行
## <核心章节>      ← 2–6 个章节，逐层深入
## Development      ← 构建/测试/lint 不超过 10 行，如有 CONTRIBUTING 则链接
## License          ← 一行

规则

标题与语气：允许带一个 emoji 的俏皮标语；正文保持克制。第一段平实地说明工具做什么、面向谁。

不要功能墙。超过 6 条的营销式要点列表是坏味道。把真实能力融入展示它们的章节中。

不要变更日志式表述（“现在支持”“3.2 新增”“即将推出”）。README 描述工具的现在时。特定版本的迁移说明放在变更日志或 docs/ 中。

长度：工具/库建议 ≤250 行，大型界面 ≤350 行。超出部分移到 docs/ 并链接。详尽的命令/参数参考应放在 docs/ 或文档站点，绝不放在 README 中——README 里放一张带链接的摘要表即可。

渐进深度：读者应能在任何章节后停下，并拥有一套适用于该使用级别的工作配置。

截图/横幅：保留现有项目素材。应用和 TUI 应在顶部附近放一张截图。压缩图片，不得超过 500 KB。

文档站点优先：当仓库有文档站点（fs-safe.io、gitcrawl.sh 等）时，README 是门面而非镜像。要链接，不要重复。

徽章行

样式：flat-square，始终动态——会过期的徽章就是 bug。绝不把版本硬编码进 img.shields.io/badge/... URL。

顺序：CI · 版本 · 平台/运行时 · 许可证 · 附加项（Homebrew、docs）。

[![CI](https://img.shields.io/github/actions/workflow/status/OWNER/REPO/ci.yml?branch=main&style=flat-square&label=ci)](https://github.com/OWNER/REPO/actions/workflows/ci.yml)

按生态添加适用的徽章：

  • npm：https://img.shields.io/npm/v/PKG?style=flat-square → npm 页面
  • GitHub release（Go/Swift 二进制）：https://img.shields.io/github/v/release/OWNER/REPO?style=flat-square
  • 运行时/平台：npm 包用 npm/node/v 徽章；只随提交变化的事实（平台、语言版本、最低 OS）可用静态 badge/platforms-... 或 badge/Swift-6.x-...
  • 许可证：https://img.shields.io/github/license/OWNER/REPO?style=flat-square
  • Homebrew：存在 formula/cask 时，用静态徽章链接 tap

CI 徽章需使用仓库实际的工作流文件名和默认分支。发布前验证每个徽章 URL 可渲染（HTTP 200 且不是 shields 的“invalid”卡片）。

各类项目模板

CLI 工具（Go/TS 二进制） —— Install（brew → go install/npm）、Quick start（3–6 条命令，配一行注释展示真实会话）、Commands（摘要表链接 docs/）、Configuration、面向智能体的 JSON/自动化输出（如有）、Development、License。

npm 库 —— Install、一个能编译的核心用法示例、然后每个能力层级一个章节（基础 → 选项 → 高级/边缘）、API 参考链接（文档站点或生成的文档）、Development、License。

Swift 包 —— 徽章（Swift 版本、平台、CI）、SPM 安装片段（含两行 Package.swift）、能编译的 Quick start 示例、能力章节、平台说明、Development、License。

macOS 应用 —— 截图优先、Install（brew cask → 直接下载链接）、对应截图的“它能做什么”导览、权限/设置说明、Development、License。

Web 服务/站点 —— 它是什么 + 托管 URL、自托管/部署路径、本地开发、架构指引、License。

验证门槛（全部强制）

  • README 中每条命令都能运行。构建仓库二进制（或安装包）并执行每个快速开始/示例命令；当执行需要凭据/硬件时，对照真实的 --help 输出验证参数。修改 README，而不是修改记录。
  • 每个代码示例都能针对当前 API 编译/通过类型检查（在仓库工具链中写一个临时文件即可）。
  • 每个相对链接都能解析到仓库中的文件；每个外链返回非 404；每个徽章都能渲染。
  • 版本事实为动态或最新：不硬编码包版本、不过期的最低要求、不对已发布的东西写“即将推出”。从 package.json/go.mod/Package.swift 中核对真实的运行时下限。
  • 从 README 中删除的既有事实内容，必须要么已在 docs/ 中、要么在同一 PR 中移入 docs/、要么确实已过时（并在 PR 描述中说明是哪一种）。