repo-health

仓库健康状况

一条命令即可审计 GitHub 仓库健康状况。生成带评分的报告，并按优先级给出修复建议。

安装

claude skill add --from https://github.com/thatrebeccarae/claude-marketing/skills/repo-health

适用场景

• 设置新仓库时，确保没有遗漏任何内容
• 定期检查活跃仓库的健康状况
• 将私有仓库开源前，确认还需要添加哪些内容
• 加入不熟悉的仓库时，评估其当前状况
• 发布前进行规范性检查

使用方法

/repo-health [repo-path]        # Full audit with scored report
/repo-health [repo-path] --fix  # Audit + generate missing files

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

---

流程

按顺序执行每个步骤。不要跳过任何步骤。

步骤 1：验证仓库路径

1. 如果提供了 repo-path，将其解析为绝对路径。如果省略，则使用当前工作目录。
2. 确认路径存在且为目录。
3. 确认其中包含 .git 目录（即这是一个 git 仓库）。

如果验证失败：

Error: {repo-path} is not a git repository.
Provide a path to a git repo or run from within one.

停止。

步骤 2：检测公开/私有状态

确定仓库的可见性：

1. 检查仓库根目录下是否有 .public-repo 标记文件 -> 公开
2. 检查远程 URL 中是否包含“public” -> 公开
3. 如果 gh 可用，运行 gh repo view --json isPrivate -q '.isPrivate' -> 使用查询结果
4. 如果以上方法都无法确定 -> 询问用户

将结果保存为 repo_visibility（公开或私有）。评分时，公开仓库的标准更严格。

步骤 3：检查文件是否存在

检查每个标准文件，并将结果记录为 PRESENT 或 MISSING。

文件	必需（公开）	必需（私有）
LICENSE	是	否
README.md	是	是
.gitignore	是	是
SECURITY.md	是	否
CONTRIBUTING.md	是	否
CODEOWNERS	建议	否
.editorconfig	建议	建议
.github/pull_request_template.md 或 .github/PULL_REQUEST_TEMPLATE.md	建议	否
.github/ISSUE_TEMPLATE/ 目录（或 .github/ISSUE_TEMPLATE.md）	建议	否
CHANGELOG.md	建议	否
CODE_OF_CONDUCT.md	建议（公开）	否

步骤 4：检查 GitHub 配置

使用 gh CLI 查询仓库元数据。如果 gh 不可用，则跳过此类别，并在报告中注明。

gh repo view --json description,repositoryTopics,hasWikiEnabled,defaultBranchRef,homepageUrl

检查每一项，并将结果记录为 PASS 或 FAIL。

检查项	标准
已设置描述	description 非空
已设置主题	repositoryTopics 至少包含 3 个主题
主页 URL	已设置 homepageUrl（如果项目有网站）
默认分支名称	defaultBranchRef.name 为 main（而非 master）
分支保护	gh api repos/{owner}/{repo}/branches/main/protection 返回 200（仅限公开仓库）
社交预览	运行 gh api repos/{owner}/{repo} 并检查是否设置了自定义 Open Graph 图片（仅供参考）

步骤 5：文档质量

README 检查：

1. README.md 是否存在（见步骤 3）
2. README 长度：少于 50 行 = WARN（过短），多于 500 行 = INFO（建议拆分）
3. 前 5 行是否包含项目描述（H1 标题或粗体文本）
4. 是否包含安装/设置说明（搜索“install”“getting started”“setup”“usage”）
5. 是否提及许可证（搜索“license”“LICENSE”）
6. 如果 /github-readme 技能可用，注明可以通过 /github:readme audit 运行更深入的 README 审计

CHANGELOG 检查：

1. CHANGELOG.md 是否存在（见步骤 3）
2. 如果存在：是否遵循 Keep a Changelog 格式（搜索 ## [ 版本标题）
3. 最近的条目是否在过去 90 天内（如果已过期，则标记为 WARN）

步骤 6：代码规范

过时分支：

git branch -r --merged main | grep -v main | grep -v HEAD
git for-each-ref --sort=committerdate --format='%(refname:short) %(committerdate:relative)' refs/remotes/

• 将超过 90 天没有提交的分支标记为过时
• 统计过时分支的总数

已跟踪的密钥/环境文件：

git ls-files | grep -E '\.env$|\.env\.|credentials|secrets'

• 任何已纳入 git 跟踪的 .env、.env.*、credentials.* 或 secrets.* 文件均判定为 FAIL

大型二进制文件：

git ls-files | while read f; do
  size=$(wc -c < "$f" 2>/dev/null)
  [ "$size" -gt 5242880 ] && echo "$f ($size bytes)"
done

• 已纳入 git 跟踪且未使用 Git LFS 的大于 5MB 的文件判定为 WARN
• 如果存在大型二进制文件，检查是否有包含 LFS 模式的 .gitattributes

依赖项新鲜度（如适用）：

• 如果存在 package.json：检查是否存在 package-lock.json
• 如果存在 requirements.txt：检查是否固定了版本（指定了版本号）
• 不要运行安装命令或修改任何内容

步骤 7：评分并生成报告

评分类别

类别	权重	涵盖内容
标准文件	30%	LICENSE、SECURITY.md、CONTRIBUTING.md、CODEOWNERS、.gitignore、.editorconfig、模板
GitHub 配置	15%	描述、主题、分支保护、默认分支
文档	25%	README 质量、CHANGELOG 是否存在及其新鲜度
代码规范	20%	过时分支、已跟踪的密钥、大型二进制文件
社区	10%	CODE_OF_CONDUCT、议题模板、PR 模板、CONTRIBUTING.md

各类别评分

每个类别根据通过的检查项评分，范围为 0–100。完整评分标准请参阅 REFERENCE.md。

字母等级

分数	等级
90-100	A
80-89	B
70-79	C
60-69	D
0-59	F

报告格式

=== Repo Health Report: {repo-name} ===
Visibility: {public | private}
Overall Score: {score}/100 (Grade: {letter})

--- Standard Files (30%) --- Score: {n}/100
  [PASS] .gitignore
  [PASS] LICENSE (MIT)
  [MISS] SECURITY.md
  [MISS] CONTRIBUTING.md
  [PASS] CODEOWNERS
  ...

--- GitHub Config (15%) --- Score: {n}/100
  [PASS] Description: "One-command repo health audit..."
  [FAIL] Topics: none set
  [PASS] Default branch: main
  [FAIL] Branch protection: not enabled
  ...

--- Documentation (25%) --- Score: {n}/100
  [PASS] README.md (142 lines)
  [WARN] No install/setup instructions found in README
  [MISS] CHANGELOG.md
  ...

--- Code Hygiene (20%) --- Score: {n}/100
  [PASS] No tracked .env files
  [WARN] 3 stale branches (>90 days)
  [PASS] No large binary files tracked
  ...

--- Community (10%) --- Score: {n}/100
  [MISS] CODE_OF_CONDUCT.md
  [MISS] Issue templates
  [PASS] PR template
  ...

=== Prioritized Fixes ===
1. [HIGH] Add SECURITY.md — required for public repos. See template in REFERENCE.md.
2. [HIGH] Enable branch protection on main — prevents force pushes and requires reviews.
3. [HIGH] Add repository topics — improves discoverability. Suggest: {topic1}, {topic2}, {topic3}.
4. [MED]  Add CONTRIBUTING.md — guides external contributors.
5. [MED]  Add CHANGELOG.md — tracks releases for users.
6. [LOW]  Clean up 3 stale branches.
7. [LOW]  Add CODE_OF_CONDUCT.md — signals welcoming community.

优先级：

• HIGH：安全、法律（LICENSE/SECURITY.md）或保护问题
• MED：影响可用性的文档和社区方面的缺漏
• LOW：清理工作和锦上添花的改进

步骤 8：修复模式（--fix）

如果传入了 --fix 标志：

1. 列出可自动生成的 MISS 和 FAIL 项
2. 请用户确认要创建哪些文件（显示编号列表，接受以逗号分隔的选项或“all”）
3. 对于每个确认创建的文件，使用合理的默认内容生成：
   • SECURITY.md：标准漏洞报告模板
   • CONTRIBUTING.md：包含代码风格说明的 Fork/分支/PR 工作流
   • CODE_OF_CONDUCT.md：Contributor Covenant v2.1
   • .editorconfig：适用于已检测技术栈的合理默认配置
   • CODEOWNERS：提示用户输入所有者模式
   • 议题/PR 模板：基于 YAML 表单的模板（参阅 REFERENCE.md）
4. 不要覆盖现有文件
5. 写入前，对所有生成的内容运行 infra/PII 脱敏处理

---

核心原则

• 默认只读。 除非明确传入 --fix，否则审核不会修改文件。
• 对公开仓库要求更高。 私有仓库跳过社区和部分配置检查。
• 优先提供可执行的结果。 每项发现都包含具体的修复建议。
• 避免无谓紧急。 推荐项的评分低于必需项。报告会区分必须修复项和锦上添花项。
• 尊重现有工作。 修复模式绝不覆盖文件，只创建缺失的文件。
• 关注基础设施/PII。 所有生成的文件在写入前都会经过标准 PII 脱敏处理。

反模式——不要

• 在标准审核期间修改任何文件（未传入 --fix 标志时）
• 运行安装命令（npm install、pip install 等）
• 推送更改或创建提交——何时提交由用户决定
• 捏造仓库元数据——使用 gh 和 git 报告的信息
• 对无法在本地访问的仓库评分——这是一个本地审核工具
• 在修复模式下生成文件时跳过 PII 脱敏