open-source-skill — 公开仓库的门禁发生在推送之前

技能好不好用是内部的事；公开仓库要回答的是另一组问题：陌生人 30 秒内能不能判断"这跟我有关吗"、装法是不是一行、说它能做的事是不是真跑过。两者的失败形态不同——内部技能死于没人用，公开仓库死于看起来像但经不起验证：README 里的命令跑不通、示例里的 token 忘了删、正文是别人课程的原段落、push 打印了成功但远端其实是空的。

两条纪律贯穿全程：格式借现成的，内容只借机制；脱敏与授权是发布前的门禁，不是发布后的清理。

1. 先找一个同类仓库当格式模板

不要发明 README 的信息组织。找一个同类、成熟、还在维护的开源 skill 仓库，照它的骨架写：一句话定位 → 一张示意图 → 一行安装命令 → 能力表格 → "为什么这么设计"。这套顺序是外部读者验证过的——他们就按这个顺序决定要不要继续读。

照它的是形状：导航结构、安装段的写法和位置、清单的呈现方式、.claude-plugin/ 的字段。不照它的内容：技能名、描述、示例、文案都不抄。借机制不借内容，这条在后面每一节都成立。

判据：拿到你的仓库，一个没听过这个技能的人，能在 README 前 10 行里答出"它是干什么的、怎么装、装完敲什么"。

2. 骨架

README.md               # 英文主：定位 → 示意图 → 一行安装 → 能力表 → 设计取舍
README_CN.md            # 等价中文，不是节选
LICENSE                 # MIT，版权人写个人号
.gitignore
.claude-plugin/
  plugin.json           # 安装器清单：name/version/description/author/license/keywords/skills
  marketplace.json      # picker 分组：name/owner/plugins[source=./]
skills/<name>/
  SKILL.md
  references/*.md
docs/                   # README 里引用的示意图（svg/png），路径必须与 README 一致

• 双语：README.md 英文主 + README_CN.md 中文等价。两份都要维护，不能一份是另一份的节选；正文语言另说（见 §8）。
• LICENSE 的版权人写个人号：公司名会把公开仓库和雇主绑在一起，这不是技术问题，是授权问题。姓名 / 年份与 plugin.json 里的 author 保持一致。
• .claude-plugin/ 的字段照参照仓库写，不要照你源仓库的现状。 一个真实落差：如果源仓库是作为 bundle patch 安装的，它可能只有 marketplace.json，没有 plugin.json（那套安装路径根本不读它）；而公开仓库要同时服务两条安装路径，两个文件都得在。这类"源仓库没有但公开形态必须有"的缺口，只能靠参照仓库发现。
• docs/ 里的图是 README 的一部分：图不在，README 的第一屏就是坏的。

3. 脱敏是门禁，不是收尾

最容易出事的一步，也最不该靠记忆做。凭记忆 grep 只能抓到你还记得的词；正确顺序是先列清单、再逐类替换、最后机械确认。

类别、替换方向、容易漏的位置，以及可直接复制的命令，见 references/desensitization-checklist.md。这里只讲纪律：

• 通过标准是 0 命中，不是"感觉没有"。对词表里每个词（大小写不敏感）全树扫，期望零结果；目录名、LICENSE 版权人、.claude-plugin 里的 author/homepage/repository 都要扫到——这些元数据位最容易被当成"不算正文"。
• 重命名会留下悬空引用：内部编号从 R013 改成 RULE-001、内部技能名换成通用说法之后，正文、索引、映射表、图里的引用都要跟着改。改完 grep 一次旧词，命中的每一处都得处理，而不是只看第一屏。
• 替身要通用，但不能空：把"某同事说"换成"评审者说"是脱敏，换成"某人说"就把信息也删了。脱敏后正文还要读得懂。
• 代码块、示例数据、截图同样在内：示例订单号、示例邮箱、终端截图里的 host 名，都是泄漏面。

4. 版权：提炼 ≠ 改写

如果内容提炼自别人的课程、文档或仓库，措辞变过不代表不算搬运。发布前做一次机械比对：

• 取来源文本与你的正文，算最长公共子串（difflib.SequenceMatcher 之类就够），阈值取 24 字符左右：低于它的重合基本是通用短语，高于它的连续重合就该怀疑是原句。
• 代码块与示例可以豁免阈值，但明显照抄的片段仍要改写或抽象化——豁免的是"代码本来就得长得像代码"，不是"整段复制"。
• 判据不是"我改了几处"，而是"读者能不能从你的正文里复原来源的段落"。能复原，就是没改够。
• 保留 attribution：讲次 / 章节编号只作溯源标签，README 里用一行写清"提炼自内部方法论课程，编号仅为可追溯，不复制原文"。注意 attribution 本身也要脱敏：不写课程名、作者、机构、内部文档链接——那些既是指向来源的线索，也是泄漏面。
• 编号去留是一个要显式做出的选择：保留可追溯（读者看不懂"07 讲"是什么，但维护者能追回来源）vs 彻底去除（干净，但失去溯源）。两种都成立，但要写出来——别默默决定，读者有权知道你留下了什么。

5. 公开仓库的提交身份

全局 git 身份常常是公司邮箱，而 commit 里的 author 是永久留存的。先看一眼：

git config --global user.name
git config --global user.email

两种换法，按维护时长选：

# 只提交一次：不改本机任何配置
git -c user.name=<personal-name> -c user.email=<personal-email> commit -m "..."

# 长期维护：只改这个仓库的局部配置
git -C <repo> config user.name  <personal-name>
git -C <repo> config user.email <personal-email>

别改全局身份——那会顺手把你公司仓库的提交也换掉。推送前用 git log --format='%an <%ae>' 看一眼实际写进去的是谁。

6. 建仓库与元数据

先在本地 commit——gh repo create --source 推的是已经提交的内容，未跟踪文件不会跟着走：

gh repo create <owner>/<name> --public --source=. --remote=origin --push
gh repo edit <owner>/<name> --description "..." --add-topic <topic> --add-topic <topic>

description 与 topics 不是装饰：外部的人找到你基本只有这三条路——搜索命中的 description、topics、README 第一行。

7. 推送成功不等于发布成功

gh repo create 打印的 URL 只证明命令跑完了。发布后要把状态读回来核对：远端可见性、默认分支、README 渲染、安装命令、文件数与本地一致、全历史没有密钥。清单要能照抄执行，见 references/release-verification.md。

最关键的两项，理由单独说：

• git diff HEAD origin/<branch> 必须为空。 push 的返回码不保证远端内容等于你本地内容——推错分支、默认分支不是你推的那条、.gitignore 多排除了一个目录，都会让你以为成功了。差异为空才是"远端 = 本地"。
• 密钥要扫全历史对象，不是扫当前文件。 一个曾经提交、后来又删掉的 key，仍然躺在对象库里能被取出来；删文件不等于删历史。这个工作区里已有专门的技能做这件事（git-secret-audit），照它的流程走，不要自己临时 grep 一遍就放行。

8. 诚实标注：没验过的要写出来

公开仓库的可信度来自"说到的都验过"。做不到的地方标出来，比含糊过去便宜得多：

• 装不了的安装方式要写明"未实机验证"。比如会往 ~/.agents 写东西的 npx skills add，在没有干净环境（或不想动本机全局状态）时就不该跑；那就别假装跑过——在 README 或提交说明里写清哪条路径未验证、为什么。
• 语言选择要显式：README 双语但正文只写中文，或反过来，都在明面上说一句（"正文中文，英文只作入口"）。默默决定会让英文读者点进来才发现读不了。
• 取舍要留痕：编号保留还是去除（§4）、要不要 vendor 上游、要不要带评测——每个都写一句"选了什么、代价是什么"。

9. 维护：源仓库修好之后，开源仓库还是旧版

这是最容易真实发生的一条：源仓库里修了一个错、补了一段，开源副本没人管，几个月后两份内容对不上，而你说不清哪份是新的。把同步当成发布的一部分，而不是一次性动作：

• 改源仓库时顺手问一句"开源副本要不要跟"。这是纪律，自动化替代不了——哪些差异是刻意的适配、哪些是漏同步，只有你知道。
• 留一个一致性检查：对同一文件在两份仓库里 diff，或对同一组计数（技能数、description 字符数）两边各数一遍。差异要么为空，要么是你显式记录过的适配。
• 如果适配不可避免（开源版必须少一处内部引用），把差异写在一个固定的地方（开源仓库的维护说明，或每次同步的提交信息）。不写，下次同步就会把适配覆盖掉。

与流程的衔接

这是一次性的发布动作，不要并行：gh repo create、git push、身份切换都是共享副作用，拆给多个 agent 只会互相打架；也不要为它开图。收尾的提交与推送可以走 /ship-it 的形态，但要知道它操作的是另一个仓库——在源仓库里 /ship-it 不会把开源仓库也更新，那正是 §9 的代价。