github-readme

GitHub README 生成器

通过项目类型检测、语气校准、可发现性指导和评分质量审计，生成、审计或更新仓库 README。

安装

git clone https://github.com/thatrebeccarae/claude-marketing.git && cp -r claude-marketing/skills/github-readme ~/.claude/skills/

适用场景

• 启动新的公开仓库，需要从头编写一份扎实的 README
• 审计现有 README 的质量、可发现性和安全问题
• 仓库发展后更新 README（新增依赖、功能或结构）
• 准备公开发布仓库，并希望优化可发现性

模式

/github:readme generate [repo-path]   # Scan repo, detect type, generate README
/github:readme audit [repo-path]      # Score existing README (read-only, 0-100)
/github:readme update [repo-path]     # Re-scan, silent audit, patch with approval

如果省略 repo-path，则默认为当前工作目录。

---

步骤 0：解析和验证

预期格式：/github:readme {mode} [repo-path]

1. 提取模式——generate、audit 或 update。如果是其他值或缺失，则显示带用法提示的错误。停止。
2. 提取 repo-path——第二个参数；如果省略，则使用当前工作目录。
3. 验证——确认路径存在、是一个目录且包含 .git。否则显示错误。停止。

保存 repo_path（绝对路径）和 mode。

---

步骤 1：扫描仓库

通过读取可用文件收集上下文。如果文件不存在，则跳过，不影响流程。

包和配置文件（技术栈检测）：

• package.json — Node/TypeScript/React
• Cargo.toml — Rust
• pyproject.toml、setup.py、requirements.txt — Python
• go.mod — Go
• tsconfig.json — 确认 TypeScript
• Dockerfile、docker-compose.yml — 容器化
• Makefile、justfile — 构建系统
• .github/workflows/ — CI/CD

目录结构：

• 在仓库根目录运行 ls，查看顶层布局
• 注意：src/、bin/、lib/、scripts/、docs/、tests/、skills/、templates/、plugins/、.github/

现有文档：

• README.md、CONTRIBUTING.md、SECURITY.md、LICENSE、ARCHITECTURE.md、CHANGELOG.md、CODE_OF_CONDUCT.md、llms.txt

Git 远程仓库：

• 运行 git -C {repo_path} remote get-url origin
• 从 URL 中提取 {owner} 和 {repo}
• 判断公开/私有：存在 .public-repo 标记则为公开；以 -dev 结尾或没有标记则询问用户

---

步骤 2：检测项目类型

根据扫描信号，将仓库归为以下一种类型：

类型	信号
工具/CLI	package.json 中包含 bin 字段、CLI 入口点、man 手册页、命令解析器（yargs、clap、cobra）
库/SDK	包含 main/exports/module 字段、发布到 npm/PyPI/crates.io，且没有 CLI 入口
合集/市场	包含多个独立项目：skills/、templates/、plugins/、recipes/ 目录中有 3 个或更多子目录
Web 应用	包含 React/Vue/Svelte/Next/Nuxt、服务端框架（Express、FastAPI、Actix）、部署配置（Vercel、Dockerfile）
个人/实验性项目	小型仓库（少于 20 个文件）、没有包发布配置、没有 CI、没有 semver 标签

如果无法明确判断，请询问用户确认。保存为 project_type。

---

步骤 3：可发现性审计

在生成或审计 README 内容之前，检查以下仓库级可发现性信号，并向用户展示发现和建议。

仓库名称：

• 是否包含丰富的关键词且易于搜索？（例如，markdown-lint-action 优于 my-linter）
• 标记通用名称：app、project、tool、my-thing

GitHub About/描述：

• 如果 gh repo view 可用，则通过它读取
• 建议为 3–8 个词，并将主要关键词放在开头
• 如果缺失或过于笼统，则建议改进

Topics：

• GitHub 最多允许 20 个 topic
• 根据检测到的技术栈、项目类型和领域建议相关 topic
• 同时包含宽泛主题（typescript、cli）和具体主题（markdown-parser、github-action）

社交预览图片：

• 如果缺失则标记，并建议创建（推荐尺寸为 1280x640px）

llms.txt（可选）：

• 如果仓库属于库/SDK 或工具/CLI，建议生成 llms.txt 文件
• 作用：帮助大模型准确理解并推荐该项目

展示可发现性建议。用户可以接受、跳过或稍后处理。这些建议不会阻止 README 生成。

---

第 4 步：生成／审查／更新

生成模式

4a. 检查是否已有 README — 如果存在，确认是否覆盖，或建议改用更新模式。

4b. 选择章节，根据项目类型确定（见下方的章节菜单）。

4c. 调整语气：

• 默认：专业的产品语气——清晰、直接，不使用模糊措辞，不堆砌营销话术
• 个人／实验性仓库，或用户明确选择：允许使用第一人称
• 绝不使用：在问题陈述中使用被动语态、在正文中使用表情符号、堆砌营销话术

4d. 生成各章节：

• 标题 + 描述 — 从软件包配置或目录中提取名称；在标题下方提供不超过 120 个字符的单行粗体描述
• 徽章 — 见下方的徽章选择
• 快速入门／安装 — 列出带版本号的先决条件、安装步骤和首次运行命令。不超过 20 行。
• 特定类型的章节 — 根据章节菜单确定。只有在扫描到足够上下文时才纳入。
• “原因”章节（仅限个人／实验性项目）— 请用户提供 2-3 句话。不得捏造。
• 许可证 — 读取 LICENSE 文件类型。用一行链接到该文件。

4e. 执行 PII／基础设施信息清理（见下文）。写入前移除违规内容。

4f. 写入 {repo_path}/README.md 并显示摘要。

审查模式（只读）

读取现有 README。不得修改任何文件。

运行质量信号检查，并按加权评分标准评分：

类别	权重	检查项
清晰度	25	是否有清晰的单行描述？标题是否具有描述性？
易用性	25	安装／设置命令是否有效？是否有代码示例？快速入门是否少于 20 行？
可信度	15	是否有徽章？徽章 URL 是否有效？是否有许可证章节？
时效性	15	版本号是否与软件包配置一致？技术栈是否与仓库一致？是否有过期链接？
安全性	20	是否泄露 PII 或基础设施信息？是否包含 API 密钥／令牌？是否包含私有主机名／IP 地址？

评分： 每个类别按 0-100 分评分，最终得分 = 加权平均分。

=== README Audit: {repo-name} ===
Score: {X}/100

Clarity:      {X}/25
Usability:    {X}/25
Credibility:  {X}/15
Currency:     {X}/15
Security:     {X}/20

PASS:
  - {passing checks}

WARN:
  - {warnings with specific detail}

FAIL:
  - {failures with specific detail and fix suggestion}

更新模式

1. 重新扫描仓库（第 1 步），检测当前状态
2. 静默审查 — 保存结果，不显示
3. 生成更新计划 — 按类别分组，采用差异格式：
   • [STRUCTURE] — 缺失／过时的章节、徽章变更
   • [CONTENT] — 过时的版本号、过时的技术引用
   • [VOICE] — 模糊措辞、营销话术、被动语态
   • [SECURITY] — PII／基础设施信息违规（自动处理）
4. 显示预览 — 以编号列表列出拟议的更改
5. 用户批准 — y（全部）、N（取消）或以逗号分隔的编号
6. 应用更改，运行最终 PII 清理，写入文件，并显示摘要

---

按项目类型划分的章节菜单

章节	工具／CLI	库／SDK	集合	Web 应用	个人项目
标题 + 描述	必需	必需	必需	必需	必需
徽章	必需	必需	必需	必需	可选
快速入门／安装	必需	必需	必需	必需	必需
使用方法／命令	必需	--	--	--	--
API 参考	--	必需	--	--	--
目录／索引	--	--	必需	--	--
功能	建议	建议	--	必需	--
配置	建议	建议	--	建议	--
架构	--	--	--	建议	--
我为何构建此项目	--	--	--	--	必需
适用对象	建议	建议	建议	--	--
贡献	建议	必需	建议	建议	--
许可证	必需	必需	必需	必需	必需

---

语气指南

类型	默认语气	示例开场白
工具/CLI	直接、实用	“为 CI 流水线快速检查 Markdown。”
库/SDK	技术性强、精准	“适用于 Stripe API 的类型化 HTTP 客户端。”
集合	组织有序、便于浏览	“50+ 个可复用的 GitHub Actions 工作流。”
Web 应用	聚焦产品、清晰明了	“实时项目仪表板，提供团队分析功能。”
个人项目	第一人称、观点鲜明	“我需要一种更好的方式来追踪阅读习惯。”

始终做到： 直接、具体、观点鲜明；段落简短（最多 4 句）。 避免： 模棱两可的措辞、营销套话、问题陈述中的被动语态、正文中的表情符号。

---

徽章选择

根据检测到的技术栈，生成 1–3 个技术徽章，并至少包含一个许可证徽章。

所有徽章都使用 style=for-the-badge。通用格式：

![License](https://img.shields.io/github/license/{owner}/{repo}?style=for-the-badge)
![GitHub Stars](https://img.shields.io/github/stars/{owner}/{repo}?style=for-the-badge)
![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white)
![Python](https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white)
![Node.js](https://img.shields.io/badge/Node.js-339933?style=for-the-badge&logo=nodedotjs&logoColor=white)
![React](https://img.shields.io/badge/React-61DAFB?style=for-the-badge&logo=react&logoColor=black)

徽章顺序：技术栈（左）→ 星标 → 许可证（右）。

---

PII / 基础设施信息清理

在所有模式下运行。扫描生成或已有的 README 文本，检查以下内容：

• 私有主机名
• IP 地址（尤其是 10.x、172.16-31.x、192.168.x、100.x Tailscale 地址）
• 内部网络/VLAN 名称
• 设备标识符或序列号
• 不应公开的客户或雇主名称
• 个人电子邮件地址
• API 密钥或令牌（sk-、token_、ghp_、Bearer、长字母数字字符串）
• 内部 Docker/服务配置（私有端口映射、容器名称）
• SSH 配置引用（别名、私钥路径）

如果发现违规内容： 列出每项内容，移除或遮盖，并告知用户移除了什么。 安全违规绝不可忽略——在更新模式下自动处理。

---

核心原则

• 先检测，不要假设。 扫描代码仓库，并根据实际内容调整结构。
• 默认保持专业。 第一人称语气是可选项，而非默认设置。
• 注重可发现性。 代码仓库名称、描述、主题和 llms.txt 都是 README 内容的一部分。
• 质量优先于完整性。 少量精心撰写的章节，胜过充斥空白占位符的冗长 README。
• 安全不容妥协。 每种模式下都必须每次运行 PII/基础设施信息清理。
• 审计模式为只读。 审计期间绝不修改文件。