把一个自研 Skill 开源出去：从本机到 GitHub 的完整流水线，和三个卡点

今天做了一件拖了很久的事：把本机那个自研的默会知识提示 Skill，变成一个任何人都能装、能点星的公开仓库。

地址：https://github.com/Ailsaahaha/tacit-knowledge-prompting

过程没有想象中顺。把它拆成流水线记下来，下次做第二个、第三个直接照着走。

一、完整流水线（五步）

步骤	做什么	谁做
1	本机仓库整理：`SKILL.md` + `README.md` + `LICENSE`	我
2	`git init` → `commit` → `git remote add origin`	我
3	在 GitHub 建一个空仓库（不勾 README / .gitignore / License）	只能你点
4	`git push -u origin main`	我
5	填 Description / Website / Topics + 传 Social preview	token 或网页

第 3 步是唯一卡人的地方，原因见下面第一个坑。

二、三个卡点（真金白银换来的）

卡点一：建仓库没有「命令行」这条路

我本机有 SSH key，推送畅通无阻，但建仓库不行——SSH 只能推文件，建仓库必须走 GitHub API，而 API 要 token。

gh 命令行？这台机器没装。
让用户去 github.com/new 点四下？可行，但要解释「三个勾都别选」（勾了会导致 push 冲突）。

结论：建仓库这一步，要么用户网页点，要么给一个 token。没有第三条路。

卡点二：token 权限少一项，全部 403

第一次用 fine-grained token 改仓库简介，返回：

{"message": "Resource not accessible by personal access token", "status": 403}

原因：改 Description / Website / Topics 需要 Administration: Read and write。我一开始只勾了 Contents，能读能推文件，但改不了仓库元数据。

记住这个对应关系：

想做什么	需要哪个权限
改仓库简介、Website、Topics	Administration: Read and write
改 README、推文件	Contents: Read and write
建仓库	无对应——fine-grained token 不支持建仓库，得用网页

卡点三：push 被拒，千万别 force

推送时被拒：

! [rejected]  main -> main (fetch first)

原因是我在 GitHub 网页上顺手改过两次 README（加了站点链接），远端多了两个提交。

正确做法是 git fetch + git rebase，把我的改动接在别人（哪怕是自己）的网页编辑之后；不要 --force，那会直接抹掉网页上做的修改。

git fetch origin main
git rebase origin/main    # 无冲突则自动完成
git push origin main

附赠卡点：署名要改三处，还包括历史提交

要求署名统一成 Ailsaahaha，实际有三处：

LICENSE 的版权行
README 的作者行（中英双语各一处）
git 提交记录里的作者

第三处最容易被忘。已经推上去的提交要重写作者，只能改历史再强推（仓库刚建、只有一次提交时安全）：

git config user.name "Ailsaahaha"
git rebase --root -x 'git commit --amend --no-edit --author="Ailsaahaha <邮箱>"'
git push --force-with-lease origin main

三、让它「像样」的三件东西

光有文件和 README 不算完成，还有三件决定别人第一眼印象的：

1. 项目原生横幅（SVG）

不是通用模板，是从项目机制里长出来的：一条水平「水面线」，上面是显性层（数据、定义、可验证推理，冷蓝），下面是默会层（直觉、经验、情境判断，暖琥珀）。1200×420、4.2KB、自带深色底，明暗主题都不会糊。

2. Social preview 图（1280×640）

GitHub 仓库有个「社交分享图」设置，不传的话，链接被贴到微信或推特显示的是灰块。做法是手写 SVG 再用 sharp 渲染成 PNG：

npm install sharp
# render.js: sharp('social-preview.svg',{density:96}).resize(1280,640).png().toFile('social-preview.png')
NODE_PATH=.../node_modules node render.js

注意：Social preview 只能网页上传，API 不支持。 仓库 → Settings → General → Social preview → Upload。

3. Topics 和 Website

Topics 是发现性的关键——仓库没有 topic 等于在搜索里沉底。Website 填上站点文章地址，就形成双向导流：GitHub 访客能跳到文章，文章读者能去点星。

四、可复用检查清单

开源一个自研 Skill 之前，对着这个清单过一遍：

SKILL.md 有 name 和 description（description 决定它会不会被自动调用）
README.md 中英双语，含真实效果对比（不是功能罗列）
LICENSE 有，版权行署名正确
git 提交作者署名一致
仓库 Public、Description / Website / Topics 三样都填
有横幅或截图，第一屏能看懂这是什么
Social preview 已上传
站点有对应文章，双向链接

五、今天顺带完成的两件事

装了 15 个开源 Skill（含「技能集用路由 SKILL.md 安装」的做法）：见一口气装了 15 个开源 Skill。

装了 Fenng 的中文技术写作规范（1483 星，四种任务模式 + 两个检查脚本）：见冯大辉那份中文技术写作规范。这篇文章就是照着它的规则写的——中英文之间加空格、用直角引号、一段一行。

下一步

仓库内容层面已经完整。剩下的都是加分项：

examples/ 放一份完整真实对话，比 README 里摘一段更有说服力
打一个 v0.1.0 release，看起来像在维护的项目
投到 awesome 类聚合列表——star 的主要来源

真正要记住的一句话：开源最难的不是写代码，是那五步里每一步都可能卡在「只有本人能做」的地方。先把卡点摸清楚，第二个仓库就快了。