nicholyx/ai-skills / custom/daily/oss-bootstrap
oss-bootstrap
Verified把一个新项目(或只有代码的裸仓库)落实为符合主流规范的开源项目——CI、治理文件、Issue/PR 模板、仓库自动化、文档体系、看板与发布流程。当用户说「新建开源项目」「给项目加上 CI / 规范」「给这个项目加上开源规范」「按热门开源项目的标准搭基建」时使用。基建就位后的日常迭代请改用 maintain-loop skill。
开源项目 Bootstrap(oss-bootstrap)
把一个裸仓库变成结构完整的开源项目。
与 maintain-loop 的关系
- 本 skill:从 0 到 1 搭基建(只做一次,或大改时回来对照)
maintain-loopskill:基建就位后,日常迭代的闭环(规划 → 实现 → 发布)
搭完基建后,一切开发工作都应切换到 maintain-loop 的流程。
第零步:先探测,再动手
本 skill 不绑定任何具体仓库。 动手前先花几分钟把下面四件事弄清楚—— 判断得出来的就自己判断,只有真正属于用户的决定才需要确认。
1. 项目类型与工具链(决定 CI 里放什么)
ls -a # 有没有 package.json / pyproject.toml / go.mod
git ls-files | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -20 # 文件类型分布
| 形态 | 静态检查 | 测试 |
|---|---|---|
| bash | shellcheck -x、bash -n | bats,或内联断言脚本 |
| YAML(Actions) | actionlint、yamllint | — |
| Go | golangci-lint | go test |
| JS/TS | eslint、tsc --noEmit | vitest / jest |
| Python | ruff | pytest |
| 内容仓库(Markdown/JSON,无构建) | 结构校验脚本、内部链接校验、编码校验 | 结构断言 |
没有构建产物不代表没有可检查的东西。 内容仓库(文档站、技能库、模板集、 配置集)最值钱的三类检查是:结构一致性(schema、frontmatter、必填字段)、 内部引用有效性(相对链接指向的文件是否真的存在)、编码卫生(替换字符、 末尾换行、非法字节序列)。这三类都不需要真的「跑」代码,成本极低而收益很高。
2. 仓库现状
gh repo view --json name,visibility,isFork,parent,hasIssuesEnabled,hasDiscussionsEnabled,licenseInfo,viewerPermission
git log --oneline | wc -l
- 是 fork 吗? fork 仓库的 Issues 默认禁用,且改不了仓库设置。脱离 fork network 只能在网页端 Danger Zone 操作,API 做不了,且不可逆
- GitHub 认出 LICENSE 了吗?
licenseInfo.key为null或显示 NOASSERTION, 多半是许可证文本里被追加了额外段落——必须保持纯许可证文本才能被识别 - 仓库是空的吗?
isEmpty: true时分支保护等设置无从谈起
3. 权限
gh auth status # 需要 repo、workflow;操作 Projects 还需要 project, read:project
缺 scope 时请用户执行 gh auth refresh -s project,read:project(这一步要用户自己跑)。
4. 仓库里现在有什么
ls -a && git ls-files | awk -F/ '{print $1}' | sort -u
已经存在的治理文件不要重写,先读一遍再决定补什么。用户可能已经有 LICENSE、 README 或 CLAUDE.md,其中有些判断值得保留。
不要一次性问用户一堆问题
语言与现状自己判断。只有这几类才需要确认:LICENSE 选型、是否已有使用者 (决定要不要留破坏性变更的余地)、仓库是公开还是私有(决定能否用 Scorecard)。
实施节奏
按阶段推进,每个组件独立分支 + 独立 PR,小批量提交,CI 全绿再合并。分支与合并 规范见 maintain-loop。
阶段一:地基 —— CI 与提交规范
这是其他一切的前提:先让「每次改动都被自动检查」跑起来。
1. CI 工作流,骨架固定为四层
- 静态检查:按语言选工具,固定版本号(可复现)。工具版本写在工作流顶部的
env:,成为唯一真源 - 测试:冒烟(快、无外部依赖)+ 集成(真实路径,能发现 mock 发现不了的问题)。 没有容器/网络依赖的检查别硬塞进需要它们的那一层
- 提交信息校验:Conventional Commits,用脚本实现(见下),同时校验 区间内的提交与 PR 标题(squash 后标题即提交信息)
ci-summary汇总 job:needs: [全部检查]+if: always(),把所有检查汇总成 一个结果。分支保护规则只需要盯这一个 check,增删检查项不用改保护规则
2. ci-summary 必须从单一真源派生,并自证完整
汇总 job 最常见的失败模式:needs / 显示名数组 / 结果变量三份手工维护的平行
列表,新增检查时漏改其中一份 —— 于是子 job 失败而汇总仍报成功。
把它写成派生的,并加断言:
declare -a jobs=("job-id:显示名" ...)
# 断言 jobs 数组与 ci.yml 的 needs 是同一个集合(比集合,不比数量——同长度互换也会漏)
cfg_ids="$(grep -m1 '^ needs: \[' .github/workflows/ci.yml \
| sed 's/.*\[//; s/\].*//' | tr ',' '\n' | tr -d ' ' | grep . | sort)"
arr_ids="$(printf '%s\n' "${jobs[@]}" | cut -d: -f1 | sort)"
[[ "$cfg_ids" == "$arr_ids" ]] || { echo "::error::汇总表与 needs 不一致"; exit 1; }
for spec in "${jobs[@]}"; do
id="${spec%%:*}"; var="R_$(printf '%s' "$id" | tr 'a-z-' 'A-Z_')"
result="${!var:-}"
# 断言:每个 id 都有对应 env,缺了就是「进了 needs 但没进判据」
[[ -n "$result" ]] || { echo "::error::needs 里有 $id 但没有 env $var"; failed=1; }
# skipped 只在确实会跳过的 job 上算良性;别处出现 skipped 说明 if 条件写错了
done
注意 tr -d '[],' 会把 needs: 这个前缀也切出来当成一个 id —— 用
sed 's/.*\[//; s/\].*//' 只取方括号内的内容。
3. 本地统一入口 scripts/lint.sh
一条命令跑完 CI 里本地能跑的那些检查。目标是「本地绿 == CI 绿」。
./scripts/lint.sh # 跑全部
./scripts/lint.sh --list # 列出检查项 id 与显示名
./scripts/lint.sh --only links # 只跑指定项
./scripts/lint.sh --skip zizmor # 跳过(如需要 docker 的那项)
设计要点:
- 四个辅助函数:
run_check/skip_check/fail_check/note - 「工具在但检查跑不起来」算失败,不算跳过 —— 静默跳过与通过无法区分
- 三个计数器 + 两类附加清单:
PASSED/FAILED/SKIPPED不足以表达 「跑了但不是 CI 同源」(本机工具版本与 CI pin 不一致)与「跑不起来(环境问题)」, 这两类在结尾单独列出 - 头部注释明确写出「不覆盖什么」,尤其:PR 标题。CI 校验 PR 标题,而标题 在 PR 建立之前不存在,本地任何入口都验不了。本地全绿不等于 commit-messages 会绿
- 入口脚本必须可执行(
chmod +x),并在 CI 里断言可执行位
4. 「本地过 = CI 过」需要有人守:lint-selftest job
lint.sh 是 CI 里被调用为零的脚本,而它的全部价值就是那条等价保证。加一个 job
断言它的行为,断言方向两两相反:
- 给自建内容注入违规 →
lint.sh必须失败,且失败原因必须是那个违规 (不是环境问题 —— 否则断言是恒真的) - 给只读 vendor 区注入同样的违规 → 必须仍然通过,且违规必须出现在输出里
- 同一份工作区跑两次,输出逐字节相同(防不确定性混进判据)
- 在不含
.git的副本里跑 → 必须明确报错退出,不能崩栈 lint.sh --list的 id 集合与ci.yml的needs集合相同
做这类测试时,副本必须是真正的 git 仓库(git init && git add -A && git commit)。
tar --exclude=.git 复制出来的目录里,所有基于 git 索引的检查器都会 exit 2,
于是「注入违规后失败」这条断言无论注入什么都成立 —— 恒真。
插入行不要用 sed 's/x/y\nz/':\n 在 GNU sed 里是换行、在 BSD sed 里是字面的
n,本地会静默不生效。用 { head -n 1 f; echo '...'; tail -n +2 f; } > tmp && mv tmp f,
并在注入后 grep 确认真的落进去了。
5. 提交信息校验脚本 scripts/check-commit-msg.sh
四种模式:--message <文本>、--file <路径>(给 git hook)、--range <区间>、
--last。类型白名单与 CONTRIBUTING.md 的类型表保持一致。
readonly ALLOWED_TYPES='feat|fix|docs|ci|chore|refactor|perf|test|style|revert|build'
readonly PATTERN="^(${ALLOWED_TYPES})(\([a-z0-9._/-]+\))?!?: .+"
必须保留的四个细节(每一个都是踩出来的):
--range用命令替换捕获,不用进程替换。done < <(git log ...)的退出码传不进while,「区间无效」与「区间内没有提交」会混成同一种「读到 0 条」,无效区间被 静默放行成「全部合规(共检查 0 条)」。改成log_out="$(git log ...)"后, 命令替换的退出码就是 git 的退出码(实测:ref/SHA 不存在 → 128,区间有效但为空 → 0)- 空区间退出 0,但措辞避开「全部合规」。CI 里
BASE..HEAD为空是合法情形 (例如只有 merge 的 PR),判失败会造假红;但 0 条检查结果什么都没验, 措辞不能说「验过了」 - 诊断顺序:先试小写化再判类型,否则
Feat: xxx会被误报成「缺少类型前缀」 while用重定向而非管道:管道会让它落进子 shell,计数器累加传不回父进程
6. 最小权限
CI 顶层声明 permissions: contents: read;需要写权限的工作流在各自文件里单独声明。
所有 run: 块开头 set -euo pipefail,多行脚本加 #!/usr/bin/env bash。
阶段二:治理文件与模板
| 文件 | 要点 |
|---|---|
LICENSE | 用户选型;纯许可证文本,不加附加段落(否则 GitHub 无法识别,显示 NOASSERTION) |
CONTRIBUTING.md | 流程、提交规范、本地检查入口。类型表必须与校验脚本逐字一致 |
CODE_OF_CONDUCT.md | Contributor Covenant 即可 |
SECURITY.md | 漏洞报告渠道 + 针对本项目的威胁模型(见下) |
SUPPORT.md | 获取帮助的分流路径:文档 → Discussions Q&A → Bug → 安全报告 |
.github/CODEOWNERS | 兜底 * @owner + 敏感路径 + 治理文件本身 |
| Issue 模板 | 用 YAML forms 而非 markdown;至少分 bug / feature / docs 三类;config.yml 关闭空白 Issue 并指向 Discussions |
PULL_REQUEST_TEMPLATE.md | 重点是「为什么」(diff 已经说明了「改了什么」);给「我如何验证」的具体示例,别让人只写「测试通过」 |
.gitignore | 语言惯例 + 编辑器目录。别依赖使用者本机的全局 gitignore —— 换机器就会暴露 |
.editorconfig | 编码、换行、缩进。*.md 要关掉 trim_trailing_whitespace(中文文档的行尾双空格是有意义的换行标记) |
.gitattributes | 换行符策略,见下 |
| 多语言 README | 顶部互相链接做语言切换;次要语言注明「完整文档以主语言为准」 |
SECURITY.md 的价值全在「威胁模型」那一节
不要照抄。先回答一个问题:这个仓库持有/分发什么? 答案不同,威胁模型完全不同。
- 持有凭证的自动化仓库(部署、发布、同步):核心风险是「谁能改工作流,谁就能
读走凭证」。列出手持凭证的 Secrets,说明已采取的防护(仅手动触发、分支保护、
表达式经
env:中转、CODEOWNERS 强制 review 工作流目录) - 分发可执行内容的内容仓库(文档、技能、模板、插件):核心风险是「恶意或误导性 内容随一次 pull 直接进入使用者的环境」。说明内容的生效范围、内容必须可审计的要求、 以及 CI 对内容的校验强度
- 库/SDK:核心风险是「使用者的输入被当作可信数据」。说明信任边界在哪
然后写出明确不在威胁模型内的情况 —— 这一节比列举防护更有价值,它能挡掉 大量「这算不算安全问题」的无效讨论。
.gitattributes:换行符策略,注意 vendor 区
# 自建内容:统一 LF。规则锚定到仓库根(/ 开头),避免波及 vendor 目录
/scripts/** text eol=lf
/custom/** text eol=lf
/docs/** text eol=lf
/*.md text eol=lf
# 二进制
*.png binary
如果仓库里有 vendored 目录(上游代码、生成产物、锁定版本的内容),不要给它写任何
属性规则。 实测教训:给 vendor 目录设 -text 会关掉 core.autocrlf 的归一化。
当 index 里是 LF、工作区是 CRLF 时(autocrlf=input 的正常状态),关掉归一化会让
「改动 vendor 文件」的 diff 显示成整文件都变了——比不加 .gitattributes 还糟。
判断方法:git check-attr text eol -- <vendor 路径> 应为 unspecified。
另外别用 * text=auto eol=lf 这种全局规则,它会匹配到 vendor 路径。
阶段三:仓库自动化
- labeler.yml:按改动路径自动给 PR 打标签(
pull_request_target,因为它不 checkout PR 代码——任何 checkout PR 代码的场景禁止用pull_request_target) - welcome.yml:首次贡献者致意(同样
pull_request_target且不 checkout 代码) - stale.yml:N 天无响应标 stale,再 M 天自动关闭;给高频使用的标签加 exempt;
operations-per-run限流(避免一次刷屏触发滥用检测);schedule用非整点 cron - release.yml:
v*.*.*tag 触发。发布说明三段式组装,见下 - dependabot.yml:每周一次,配 7 天 cooldown(新版本有 bug 或 tag 被改投恶意
代码时,冷却期让它先暴露);用
groups把同一依赖的 minor/patch 合并成一个 PR
三段式发布说明
人工归纳 + 机器枚举 + 可选润色,三个输入源各自独立降级、任一缺失都不阻断发布:
- CHANGELOG 手写段(
awk以^## \[为分隔提取本版本) - GitHub 原生
releases/generate-notes—— 它返回自上一个 tag 以来的 PR 列表、 贡献者、以及 Full Changelog 对比链接。自己拼这些既麻烦又容易漏 - 可选 AI 摘要 —— 配了 key 才启用,任何失败都
exit 0。摘要绝不能成为 发布的单点故障
组装顺序即优先级:摘要(> 引用块)→ 手写正文 → --- 分隔线 → 机器清单。
没有 AI key 时走降级路径,发布照常成功。
tag 过滤器末尾要加 *(如 v[0-9]+.[0-9]+.[0-9]+*),否则预发布 tag
根本不触发工作流,预发布逻辑成死代码。预发布版本(tag 含 -)不标 latest。
创建 Release 走「先查后建」:gh release view 成功后改走 gh release edit。
网络抖动时 git push 可能「显示失败、远端已成功」,重试会重复推 tag、触发两次
工作流,第二次 gh release create 因已存在而 422。
供应链加固(对标 OSSF Scorecard)
| 加固项 | 做法 |
|---|---|
| Actions pin 到 commit SHA | uses: actions/checkout@<40 位 SHA> # v7——tag 可移动而 SHA 不可;注释保留版本,Dependabot 的 PR 照常更新 SHA。用 gh api repos/<owner>/<repo>/commits/<tag> --jq .sha 查真实的 SHA,不要编造 |
| checkout 不留凭证 | 每个 checkout 加 persist-credentials: false |
| 工作流安全扫描 | CI 加 zizmor job(容器按版本 pin,挂载 :ro)。基线保持 0 findings,豁免集中在 .github/zizmor.yml,每条豁免必须写明可验证的安全依据 |
| CLI 工具按内容固定 | 不用 apt-get、不用 runner 预装版本(它们随镜像更新漂移,是「本地绿 CI 红」的常见来源)。下载 release 后 sha256sum -c 校验;release 不提供校验和文件时,把 sha256 写进工作流顶部固定 |
| OSSF Scorecard | ossf/scorecard-action + publish_results: true(需要 id-token: write)。仅公开仓库;私有仓库必须设为 false。README 加徽章,供应链安全从「自觉做得好」变成「有公开体检报告」 |
| 最小权限 | 每个工作流显式声明 permissions,绝不放任仓库默认(宽)权限 |
先跑 lint.sh 看 zizmor 实际报什么,再针对真实告警写豁免。 不要预先编造豁免
条目——预先创建的空配置或猜测性豁免,恰恰会让人以为「已经评估过了」。
注意:给 step 插入 with: 块这类结构调整,逐个手工做。批量脚本会算错缩进层级
弄坏 YAML(判断依据:修改对象是「字符」还是「结构」)。
仓库标签体系补齐:在默认标签外建项目标签,gh label create <名> --color <色> --description <说明>。
阶段四:文档体系
- README:面向使用者。结构:这是什么 / 特性 / 快速开始 / 参数速查 / 常见场景 / 项目结构 / 文档索引 / 路线图 / 贡献 / 许可证
docs/四件套:USAGE.md:从零跑起来的全部步骤 + 每个参数详解 + 常见场景ARCHITECTURE.md:面向想改代码的人。写「为什么这样设计」并记录被否掉的方案 ——「我们试过 X,因为它会导致 Y,所以选了 Z」比列出目录结构有用得多TROUBLESHOOTING.md:现象(保留报错原文,使用者拿它搜索)/ 原因 / 解决; 写明「什么情况下不该用这个方案」MAINTAINER_GUIDE.md:维护者手册 + 仓库配置清单 + 项目红线
CHANGELOG.md:Keep a Changelog 格式,[Unreleased]段 + 固定六分类 (新增/变更/弃用/移除/修复/安全),不自创分类
写完文档要核对两件事:提到的每个参数/选项/文件是否真实存在、内部相对链接是否
全部有效(写个十几行的脚本扫一遍,或直接复用 lint.sh 的链接检查)。
文档与代码同步演进:改了行为不改文档,等于没有改。
阶段五:仓库设置(gh api / gh 命令)
这些不在代码里,要用 API 落实,并且记录进 MAINTAINER_GUIDE 的「仓库配置清单」 —— 换机器或重建仓库时需要重做。
# 分支保护:要求汇总检查通过、严格同步最新、过期评审自动清除、
# 禁止 force push 与删除、必须解决所有对话
gh api repos/{owner}/{repo}/branches/main/protection -X PUT --input - <<'JSON'
{ "required_status_checks": {"strict": true, "contexts": ["CI 总览"]},
"required_pull_request_reviews": {"dismiss_stale_reviews": true, "required_approving_review_count": 0},
"enforce_admins": false, "restrictions": null,
"allow_force_pushes": false, "allow_deletions": false,
"required_conversation_resolution": true }
JSON
contexts用的是检查的显示名(汇总 job 的name:),不是 job id- 单人维护的仓库用
required_approving_review_count: 0——不要求别人审批,但 CI 仍是硬门禁 enforce_admins: false让管理员仍可直接推送,是「软门禁」;要硬门禁就设true- 分支保护必须在 CI 落地之后才启用,否则所有 PR 会因缺必需检查而卡死
其余:开启 Discussions(承接使用提问)· Projects 看板 gh project create ·
Roadmap Issue 作为路线图单一事实来源 · 第一个里程碑 vX.Y.Z · 补齐标签。
需要用户手动配置的(Secrets、网页端开关)列一张清单告知,不要默默跳过。
阶段六:验证与首个发布
- 全流程演练:开一个真实的小 PR(哪怕是文档),完整走一遍 分支 → PR → CI → review → squash merge → Issue 自动关闭。 基建只有在第一次真实使用时才算真正搭好
- 首个 Release:CHANGELOG 归档 v1.0.0 → 发布 PR → tag 推送 → 验证发布说明三段齐全
- 交接:向用户汇报搭建清单(建了什么、在哪、还差什么需要手动配置)
踩坑记录(与 maintain-loop 互补)
run-name里的#:run-name: 为 PR #${{ ... }}中#前有空格会被 YAML 当注释,表达式被吞掉。含#的行要加引号。yamllint 能发现- 注释里出现 shellcheck 指令字样会被当成真指令,触发莫名的 SC1072/SC1073。改措辞
shellcheck版本差异:本地新版不报的告警 CI 旧版会报。所以要么两端同版本, 要么按内容哈希 pinset -u下空数组:"${arr[@]}"在 bash 3.2(macOS 自带)会抛 unbound variable, bash 4.4+ 才改掉。遍历前先判${#arr[@]}pipefail+$(cmd) || return 1:命令输出了有效内容但退出码非零时,会把成功 当失败。判据应该是「有没有拿到内容」,而不是退出码- 判断成败禁止管道接
tail/head:if cmd | tail -1; then判断的是tail的退出码。用if out="$(cmd 2>&1)"; then,输出打印放在判断之后 pull_request_target+ checkout PR 代码 = 任意代码以可写 token 运行,绝对禁止- 所有用户输入(
workflow_dispatchinputs 等)经env:中转进脚本,${{ }}不直接 写进run:——表达式注入 gh pr create的正文用--body-file <临时文件>,不要用嵌套 heredoc:--body-file - <<'EOF'放进$(...)里、外层又套一个循环时,-拿到的 stdin 是空的,PR 正文静默丢失gh只认origin:分支推在别的 remote 上时gh pr create报you must first push the current branch to a remote。加--head <owner>:<branch>- 每次编辑中文/非 ASCII 内容后全仓扫描 U+FFFD 替换字符。多轮迭代中反复出现 「写入时混入替换字符」,这条必须执行,不要省
完成标准
- CI 覆盖静态检查、测试、提交规范,且有一个汇总 check
- 汇总 check 自证完整(
needs与显示名数组是同一集合) - 分支保护启用,且只依赖汇总 check
-
scripts/lint.sh可用,且有一个lint-selftestjob 守它 - 治理文件齐全,LICENSE 能被 GitHub 识别
- labeler / welcome / stale / release / dependabot 全部就位且跑过至少一次
- 供应链基线达标:
uses:全部 pin 到 SHA、checkout 全部persist-credentials: false、 zizmor 0 findings(豁免有据) - docs 四件套 + CHANGELOG 就位,README 的参数与内部链接经过校验
- 看板、Roadmap Issue、第一个里程碑就位
- 一个真实 PR 从头到尾走通过,首个 Release 已发布
- 移交清单已告知用户(需手动配置的 Secrets、网页端开关)
之后的一切迭代,切换到 maintain-loop skill。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |