让 coding agent 先理解仓库，再写出高级、简单、舒适的 GitHub 项目 README。
内容设计决定写什么，视觉设计决定怎样让人舒服地看到，仓库证据保证两者都不失真。
README 不是项目资料的机械汇总，也不只是 Markdown 美化。一个真正好用的 README，需要 agent 同时完成两类工作：
| 层次 | 要解决的问题 |
|---|---|
| 内容设计 | 项目是什么、适合谁、为什么值得用、怎样得到第一个成功结果。 |
| 视觉表达 | 如何用层级、示例、截图、徽章、表格和图表，让信息更容易浏览。 |
通用模板很难判断哪些章节对当前项目重要，普通生成器也无法确认安装命令、脚本、路径和许可证是否真实。github-readme 把这些判断封装成一条 Agent Skill 工作流：
理解仓库 → 识别读者 → 设计结构 → 完成 Quick Start → 选择视觉元素 → 验证事实
最终目标不是“生成一份很长的 README”，而是让访客快速回答：
这是什么？ → 适合我吗？ → 怎样成功运行？ → 常见用法是什么？ → 下一步去哪里？
pi install https://github.com/Windrunner20/github-readme-skill重启 pi，进入目标项目：
cd your-project
pi然后直接提出目标：
请使用 github-readme skill，为当前项目写一个高级、简单、舒适的 README。
主要读者是第一次使用这个项目的开发者。
当 agent 开始读取当前仓库的 README、manifest、入口、示例或 CI 文件时，说明 Skill 已经开始工作。完成后，它会说明改了什么、验证了什么，以及哪些事实仍需人工确认。
/skill:github-readme
正常情况下，用户直接提出“写 README”“补 Quick Start”“简化项目介绍”“让 README 更漂亮”等任务时，pi 也可以根据 Skill 描述自动加载它。
其他安装方式
git clone https://github.com/Windrunner20/github-readme-skill.git
mkdir -p ~/.agents/skills
cp -R github-readme-skill/skills/github-readme ~/.agents/skills/github-readmepi 会自动发现 ~/.agents/skills/github-readme/SKILL.md。
your-project/
└── .agents/
└── skills/
└── github-readme/
├── SKILL.md
├── references/
└── scripts/
项目级 Skill 会随仓库共享，并在用户信任项目后加载。
该 Skill 遵循 Agent Skills specification。其他兼容实现可以加载同一个 skills/github-readme 目录；发现路径和信任机制以对应 agent 文档为准。
请使用 github-readme skill 创建根目录 README.md。
README 使用中文，主要读者是第一次使用这个 CLI 的开发者。
先展示项目价值和最短成功路径，不要套大而全的模板。
请使用 github-readme skill 改进现有 README。
保留部署、benchmark 和致谢，简化首屏，修复过期命令与本地链接。
请使用 github-readme skill 重写 README。
希望整体专业、克制、有高级感；参考同类型优秀项目设计首屏。
可以使用已有截图、少量徽章和 Mermaid，但每个元素都要有读者价值。
当前 README 太长。请保留采用和使用项目所需的信息，
把完整配置、架构和排错内容链接到 docs，不要丢失重要限制。
请使用 github-readme skill 审查 README，不修改文件。
按读者影响排序，区分事实错误、采用障碍、视觉噪音和编辑建议。
| 目标 | 不是 | 应该是 |
|---|---|---|
| 高级 | 大 Banner、徽章墙、营销形容词 | 信息有取舍、事实可追溯、状态和限制诚实、视觉克制 |
| 简单 | 只有一条安装命令 | 一条主要路径、一个好例子、最少但足够的信息 |
| 舒适 | 堆很多图片和折叠块 | 首屏可理解、命令可复制、成功结果明确、下一步容易找到 |
高级不等于花哨，简单不等于缺信息，舒适也不等于没有深度。Skill 优化的是读者完成任务时的认知成本。
flowchart LR
A[用户目标] --> B[读取仓库证据]
B --> C[识别读者与项目类型]
C --> D[设计内容结构]
D --> E[设计视觉表达]
E --> F[写入或改进 README]
F --> G[静态检查与人工复核]
- 理解任务：判断创建、改写、简化还是审查，识别目标读者、语言和保留项。
- 读取证据：检查 manifest、锁文件、入口、示例、测试、CI、许可证和已有文档。
- 审计现状：把已有内容分成保留、修复、删除和待确认。
- 设计认知漏斗：先回答“是什么、适不适合、怎样成功”，再展开配置、API 和背景。
- 完成 Quick Start：不仅给命令，还给前置条件、首次调用和成功信号。
- 设计视觉层：参考同类型优秀 README，选择截图、Demo、徽章、Mermaid、表格或
<details>。 - 验证事实：核对脚本、路径、链接、锚点、许可证、图片和模板残留。
- 报告边界：说明哪些内容经过静态或运行时验证，哪些仍需项目所有者确认。
完整工作流见 SKILL.md。
Skill 不强制万能模板，而是根据项目形态调整重点：
| 项目类型 | README 优先回答 |
|---|---|
| 库 / SDK | 怎样安装、怎样 import/use、返回什么、兼容哪些版本、完整 API 在哪里 |
| CLI / TUI | 输入什么命令、得到什么输出、会修改什么、配置和 --help 在哪里 |
| Web / 桌面应用 | 面向谁、界面如何、怎样启动、打开哪个地址、依赖哪些外部服务 |
| 服务 / API | 怎样启动、健康检查是什么、最小请求/响应、认证和数据边界是什么 |
| Plugin / Agent Package | 宿主平台、安装与启用、权限、调用方式、兼容要求 |
| 文档仓库 | 目标读者、阅读路径、适用版本、如何预览和贡献内容 |
| Monorepo | 整体地图、根工作流、workspace 命令、package-level README 导航 |
详细建议见 project-shapes.md。
当用户要求“漂亮”“专业”“高级感”时，Skill 会读取 visual-design.md，并遵循这些原则：
- 先研究同类型项目的优秀案例，而不是只找最花哨的 README；
- 首屏平衡项目身份、清晰定位、可信状态和真实效果；
- 优先使用仓库已有 Logo、截图、终端输出和 Demo；
- 徽章通常控制在 3～6 个，并链接到真实证据；
- Mermaid 只在一张图能明显降低解释成本时加入；
- 表格只用于小型、规则的数据；
<details>隐藏可选方案，不隐藏前置条件、警告和唯一用例；- 重要信息保留为文本，即使远程图片失效也能理解项目；
- 发布任务完成后检查 GitHub 的实际渲染结果。
默认不会加入个人连续提交卡、热门语言卡、贡献蛇、个人活动图、无数据来源的徽章或与项目使用无关的动画。它们更适合 Profile README，而不是项目文档。
Skill 附带一个零依赖、只读的 README 检查器。Node.js 22.19+ 可用时，agent 可以在目标项目根目录运行：
node /path/to/github-readme-skill/skills/github-readme/scripts/check-readme.mjs README.md --strict它检查：
- 唯一 H1、标题层级和 fenced code block；
- 本地链接、图片路径和内部锚点；
- npm、pnpm、yarn、bun 脚本；
- Makefile、Python requirements、Cargo、Go 和 Compose 文件证据；
- 空章节、模板占位符、Quick Start 和成功信号；
- 许可证冲突、疑似密钥和危险复制命令。
它不会联网，也不会执行 README 中的安装、迁移、部署或删除命令。PASS 代表通过机械一致性检查，不代表运行时命令已经真实执行。
github-readme-skill/
├── skills/github-readme/
│ ├── SKILL.md
│ ├── references/
│ │ ├── project-shapes.md
│ │ └── visual-design.md
│ └── scripts/
│ ├── check-readme.mjs
│ └── readme-check.mjs
├── test/readme-check.test.mjs
├── research/
├── CONTRIBUTING.md
└── LICENSE
需要 Node.js 22.19 或更高版本。
npm test
npm run check成功时：
README check: PASS
Diagnostics: 0 error(s), 0 warning(s), 0 notice(s)
本项目的 GitHub Actions 会在每次 push 和 pull request 中运行测试与 README 检查。贡献说明见 CONTRIBUTING.md。
核心资料：
- GitHub Docs — About READMEs
- GitHub Docs — Creating diagrams
- Make a README
- Art of README
- Standard Readme
- Awesome README
- Best README Template
完整研究报告见 research/README-research.md。
Skill 是会被 agent 加载的指令，附带脚本也可能由 agent 执行。安装第三方 Skill 前应审查源码。
本项目的检查器只读、离线，不执行 README 中的命令，拒绝访问项目根目录之外的路径，也不会保存仓库内容。
MIT © 2026 GitHub README Skill contributors