dancolta/github-repo-audit
GitHub: dancolta/github-repo-audit
一款基于 Claude Code 的多 agent 审查工具，用于诊断和改进 GitHub 仓库的 README、定位与可发现性，帮助开源维护者提升项目展示效果。
Stars: 1 | Forks: 1
# github-repo-audit
[](https://opensource.org/licenses/MIT) [](https://docs.anthropic.com/en/docs/claude-code) [](https://github.com/dancolta/github-repo-audit)
**并行从 5 个维度审查你的 GitHub 仓库的对外展示面。**
*专为那些工作成果被糟糕的 README 埋没的独立开源维护者打造。*
你的 README 应该让人感觉像 [ripgrep](https://github.com/BurntSushi/ripgrep) 或 [bat](https://github.com/sharkdp/bat) 的 README 一样——立场鲜明、易于扫读，并且对自己的定位有清晰的认知。而不是像一个 SaaS 着陆页。
## 工作原理
```
flowchart LR
A[/github-repo-audit URL/] --> B[Intake: ground truth]
B --> C{5 agents in parallel}
C --> D1[competitive-analyst]
C --> D2[market-researcher]
C --> D3[product-strategist]
C --> D4[ui-ux-designer]
C --> D5[content-marketer]
D1 & D2 & D3 & D4 & D5 --> E[Synthesis]
E --> F[Severity-ranked issue list]
F --> G{Approval gate}
G -->|approved| H[Apply: README + gh repo edit]
G -->|rejected| I[Stop, no writes]
```
1. **信息收集** — 你粘贴一个仓库 URL（或指定一个本地路径），并提供一段简短的“这个产品究竟是什么”的描述。如果你跳过了这段描述，该 skill 会根据你的 README 起草一段，并要求你确认。
2. **五个 agent 并行** — 每个 agent 负责审查你仓库对外展示面的一个维度，并返回不超过 800 字的结果。
3. **你审批，skill 执行** — 综合结果将生成一个按严重程度排名的问题列表（严重/高/中/低）。由你决定应用哪些修复。没有你的签字同意，任何内容都不会写入磁盘或触发 `gh repo edit`。
## 安装说明
```
mkdir -p ~/.claude/skills && \
git clone https://github.com/dancolta/github-repo-audit ~/.claude/skills/github-repo-audit
```
就是这样。该 skill 现在可以通过 `/github-repo-audit` 使用（并且会在诸如 "audit my repo" 或 "rewrite my readme" 等短语上触发）。
## 使用方法
```
/github-repo-audit https://github.com/yourname/yourproject
```
然后回答关于事实基础的问题，观察 5 个 agent 并行运行，审查问题列表，并批准你希望应用的修复。
## 审查内容
这 5 个维度：
1. **竞争格局** — 从你所在类别中 5–10 个高星 OSS README 中提取模式
2. **目标用户的痛点话术** — 来自 Reddit、HN、X、开发者论坛的原汁原味的词汇
3. **产品定位** — 反向定位话术、对比表维度、一句话推介
4. **README 视觉层级与素材规范** — 首屏蓝图、核心素材（hero asset）的有无及尺寸、badge 规范（最多 3 个）、TOC（目录）和折叠面板模式。视觉*设计*判断仍需人工审查。
5. **SEO 与 AI 引用展示面** — GitHub topic 标签、Google 关键词映射、Perplexity/ChatGPT/Claude 引用区块
## 产出内容
- `synthesis.md` — 汇总所有 5 个 agent 的分析结果
- `issues.md` — 带有建议修复方案的严重/高/中/低问题列表
- `README.md` — 按照固定的章节顺序重写
- `github-metadata.md` — About 描述 + topic 标签 + 建议的仓库名称
- `hero-shotlist.md` — 针对核心素材的逐帧规格说明
## 配套 skill
[`claude-gif`](https://github.com/dancolta/claude-gif) — 可选。如果安装了它，审查过程会提供选项，将核心素材的分镜列表渲染为实际的 GIF。没有它审查过程也能端到端完成；你只是得到规格说明而不是实际文件。
## 效果对比
| | github-repo-audit | ChatGPT 提示词 | README 生成器 | 手动重写 |
|---|:---:|:---:|:---:|:---:|
| 审查完整的对外展示面（名称、About、topics、核心素材、README） | ✓ | ✗ | ✗ | 部分 |
| 多 agent：竞争 + 市场 + 产品 + UI/UX + SEO | ✓ | ✗ | ✗ | ✗ |
| 在进行任何编辑前列出按严重程度排名的问题列表 | ✓ | ✗ | ✗ | ✗ |
| 应用修复前的审批环节 | ✓ | ✗ | 不适用 | 不适用 |
| 坚决抵制 AI 套话表达（emoji 标题、"unleash"、无意义废话等） | ✓ | ✗ | ✗ | 部分 |
| 通过 `gh repo edit` 应用修复（topics、About、名称） | ✓ | ✗ | ✗ | 部分 |
| 保留维护者的语气风格 | ✓ | ✗ | 部分 | ✓ |
| 产出有效差异（diff）所需时间 | ~5 分钟 | ~30 分钟提示词调试 | 数小时套用模板 | 数天至数周 |
## 常见问题解答
这个 skill 可以用于私有仓库吗？
可以。审查过程会读取本地仓库，并且对于 README 可以完全离线工作。`gh repo edit` 步骤需要通过 `gh auth status` 验证；如果你未经过身份验证，该 skill 会输出一段可直接复制粘贴的命令块，而不是自动执行它们。如果 5 个 agent 意见不一致怎么办？
只有当冲突涉及核心关键点时——例如相互矛盾的定位描述、分类决策或重命名建议——协调器才会向你提示冲突。风格上的差异会被自动合并。你不需要去仲裁每一个微小的分歧。它会在没有警告的情况下覆盖我的 README 吗？
不会。每一次文件写入和每一次 `gh` 变更操作都需要你的明确批准。这 5 个研究 agent 全部以只读模式运行。它适用于 monorepo 吗？
它会审查根目录的 README。子包的 README（`packages/*/README.md`）不在审查范围内——如果你需要审查这些文件，请在对应的包目录中重新运行该 skill。这与 README 生成器有什么区别？
README 生成器是从零开始创建文档。而 github-repo-audit 会分析现有的 README 和仓库展示面，找出具体的定位、清晰度和可发现性方面的差距——它面向的是那些已经有可用产品，但对外展示效果不佳的维护者。什么是 Claude Code skill？
Claude Code skill 是一个可复用的命令文件（一个内嵌指令的 Markdown 文件），它针对特定工作流扩展了 Claude Code 的行为。github-repo-audit 就是一个充当协调器的 skill，它会生成专门的子 agent 来审查仓库的对外展示面，并应用已批准的改进方案。标签：AI智能体, Claude Code, 多智能体协同, 开源项目运营, 文档优化, 自动化审查, 防御加固