Skill Publisher

一键将 agent skill 发布到 GitHub，自动完成验证、README 质量检查、补全、推送和真实安装验证。

前置条件

• gh CLI 已安装且已登录（gh auth status）
• Skill 目录包含有效的 SKILL.md（含 YAML frontmatter name + description）
• 优先使用 /Users/joe/.agents/skills/<name> 作为正式源目录；.codex / .claude 可作为兼容入口。

发布流程

当用户要求发布 skill 时，运行发布脚本：

python3 ~/.agents/skills/qiaomu-skill-publisher/scripts/publish_skill.py <skill_dir>

确定 skill 目录

• 如果用户说"发布这个 skill"且当前在某个 skill 目录 → 用当前目录
• 如果用户指定了 skill 名称 → 优先在 ~/.agents/skills/ 下查找
• 如果不确定 → 问用户要发布哪个 skill

脚本自动完成的步骤

1. 验证 SKILL.md 的 YAML frontmatter（name + description）
2. 检查 gh CLI 就绪状态
3. 创建 LICENSE（MIT，如果缺少）
4. 生成或检查 README.md：生成时不再写 TODO 模板；已存在时拦截明显占位符
5. 识别仓库名：优先使用当前 origin 仓库名，避免把 skill-publisher 误发到错误 repo
6. 初始化 git（如果需要）
7. 创建或更新 GitHub 公开仓库并推送
8. 验证 npx skills add --list 可发现，并在临时目录真实安装

参数选项

| 参数 | 说明 | |------|------| | --private | 创建私有仓库（默认公开） | | --dry-run | 仅检查，不实际发布 | | --skip-verify | 跳过 npx skills 验证 | | --github-user USER | 指定 GitHub 用户名（默认自动获取） | | --repo-name NAME | 指定 GitHub 仓库名；默认优先使用当前 origin 仓库名，否则使用 skill name | | --no-symlink | 跳过同步 ~/.agents/skills/ 实体目录 |

自动同步 ~/.agents/skills/ 实体目录

发布成功后，脚本可自动把 skill 同步到 ~/.agents/skills/<name> 作为实体目录。

这个目录是通用 Agent Skills 标准目录，以下工具会自动读取： OpenCode、Codex CLI、Cursor、Gemini CLI、GitHub Copilot、Amp、Cline、Warp 等。

一次发布，多工具共享，无需重复配置。

如果当前发布源已经是 ~/.agents/skills/<name>，脚本会跳过同步，避免误删自己的源目录。若 skill name 与 repo name 不一致，或者你不想产生本地副本，发布时加 --no-symlink。

⚠️ SKILL.md YAML 安全规则（发布前必查）

npx skills 使用严格 YAML 解析器，以下写法会导致安装失败（报 "No valid skills found"）：

| ❌ 错误写法 | ✅ 正确写法 | |-----------|-----------| | description: 含有 "引号" 的文字 | 改用 \| 块标量（见下方） | | description: 含单引号'的文字 | 改用 \| 块标量 | | description: 含冒号: 的文字 | 改用 \| 块标量 |

最安全的 description 写法：

description: |
  描述放这里，可以随意包含 "双引号"、'单引号'、冒号: 等特殊字符
  触发词: 用户说...时触发

脚本已内置 YAML 严格校验（pyyaml），会在发布前捕获这类错误并给出修复提示。

更新已发布的 skill

对已有 GitHub 仓库的 skill 再次运行同一命令，脚本会检测到仓库已存在，自动 commit + push 更新。

使用示例

用户：发布 yt-search-download 这个 skill
执行：python3 ~/.agents/skills/qiaomu-skill-publisher/scripts/publish_skill.py ~/.agents/skills/yt-search-download

用户：把当前 skill 发到 GitHub
执行：python3 ~/.agents/skills/qiaomu-skill-publisher/scripts/publish_skill.py .

用户：先检查一下能不能发布
执行：python3 ~/.agents/skills/qiaomu-skill-publisher/scripts/publish_skill.py <dir> --dry-run

用户：当前 skill name 与仓库名不同，明确发布到 qiaomu-skill-publisher
执行：python3 ~/.agents/skills/qiaomu-skill-publisher/scripts/publish_skill.py <dir> --repo-name qiaomu-skill-publisher

README 质量检查（发布前必做）

脚本只在 README 不存在时自动生成一个发布页模板。发布前，必须人工检查/撰写 README，确保它对陌生用户有价值。

最新标准：自动生成的 README 不应包含 TODO、特性 1、[问题 1] 这类占位符；已有 README 如果包含明显占位内容，发布会失败。

README 必须包含的 7 个要素

1. 价值主张（Hook）：第一段就让用户明白"这能解决我什么问题"，用具体场景描述，避免抽象描述
2. 首屏证据：产品截图、输出样例、真实生成物或短 Demo 必须出现在 README 第一屏附近；Web 项目优先放完整产品截图
3. 动态可信信号：GitHub stars、forks、issues、last commit、license、deploy/install 按钮等徽章要放在顶部；适合公开传播的项目加 Star History
4. 前置条件清单（checkbox 格式）：用 - [ ] 列出所有依赖，让用户逐一确认。每条都要写清楚怎么装，不能只说"需要 xxx"
5. 完整安装步骤：编号步骤，细到小白能跟着做。每步都提供验证命令（如 --version）
6. 自然语言使用示例：展示 2-3 个用户真实会说的句子，让人一眼看懂怎么触发
7. 致谢原作者：如果 skill 基于第三方工具/库，必须注明原项目链接和作者
8. 必要的风险/限制说明：写操作、账号相关、费用相关的风险需明确告知
9. 常见问题/Troubleshooting：至少列出 3 个常见报错和解决方法，降低用户放弃率

Web 项目 README 发布标准

参考 nexu-io/open-design 这类高转化 README，Web 项目不能只写安装命令，必须像产品发布页一样给用户一个可判断的首屏。

首屏顺序建议：

1. 项目名 + 一句话 Hook
2. 主要 CTA：Deploy with Vercel / Live Demo / Install，按钮要能直接用真实仓库 URL
3. GitHub 动态徽章：stars、forks、issues、last commit、license、build 状态（如果有）
4. 产品截图：docs/assets/product-screenshot.png，alt 写清楚截图内容
5. 3-6 个核心功能点，不写泛泛的"高效/现代/优雅"

Web 项目必须优先补齐：

• docs/assets/product-screenshot.png：首屏或核心工作流截图
• docs/assets/ 下的样例输出：如图片生成网站放 3-6 个代表性生成图
• README 中的样例表格：展示输入、输出、关键差异或使用场景
• scripts/capture-screenshots.* 或等价命令：能本地启动网站后自动刷新 README 截图
• 部署说明：Vercel/Netlify/Docker 等入口必须使用真实仓库 URL 和最少步骤

推荐 README 模块：

# Project Name

> 一句话说明用户会得到什么。

[Deploy with Vercel] [Live Demo] [Stars] [Forks] [Last commit] [License]

<img src="docs/assets/product-screenshot.png" alt="..." />

## 为什么值得用
## 样例输出
## 一键部署
## 本地开发
## 自动更新截图
## 数据/生成流程
## Star History
## Troubleshooting

自动截图要求：

• 有前端 UI 的项目，优先用 Playwright/Puppeteer 生成 README 截图，不手工截屏
• 截图脚本应允许通过环境变量指定 URL，例如 SCREENSHOT_URL=http://127.0.0.1:3000 npm run capture:screenshots
• 截图文件放进 docs/assets/，README 使用相对路径引用
• 截图脚本是发布资产生成，不等同于功能验收；除非用户要求，否则不要把它包装成完整 E2E 测试

语言原则

默认写中英双语 README，但中文在前。 中文用户是主要受众，英文是给国际用户的补充。

双语结构（中文在前）：

# skill-name

> 中文一行价值主张
> One-line English hook

**[中文](#中文) | [English](#english)**

---

<a name="中文"></a>
## 中文
[完整中文内容]

---

<a name="english"></a>
## English
[完整英文内容]

README 吸引力写法（最重要）

目标不是"让人看懂"，而是"让人想装"。 每一段都要回答用户心里那个问题：这和我有什么关系？

高吸引力 README 的结构：

1. 第一句话抓痛点：描述用户现在的痛，不是你的方案。一句话，精准，不废话。

   • ✅ "你问 AI 一个难问题，它给你一个答案，一个角度。"
   • ❌ "这是一个多视角推理工具，基于 arXiv:2605.02396..."

2. 一句话翻转：立刻给出"用了这个之后"的对比。

   • ✅ "HeavySkill 让 K 个独立 AI 并行思考同一个问题，然后让 Codex 主持讨论，综合出一个比任何单一答案都更扎实的结论。"

3. 具体输出预览：告诉用户他会得到什么。不要说"生成报告"，要说"生成一个 Medium 杂志风格的 HTML 报告，有每个视角的推理过程，有讨论中发现的盲点，有一个加粗的最终判断"。

4. 首屏截图或样例：让用户先看到真实结果，再决定是否继续读。Web 项目放产品截图，生成类项目放代表性输出，CLI/Skill 放实际终端输出或生成文档片段。

5. 一行安装：最低摩擦。不要说"先 clone 再 cd 再 npm install"。

   npx skills add username/skill-name
   

6. 自然语言触发示例：让用户知道怎么用。不是命令，是他会真实说出的话。

   • "讨论一下 React vs Vue"
   • "think harder: 微服务还是单体架构"

7. 前置条件清单（checkbox 格式）：放在安装之后，不要放开头吓人。用 - [ ] 格式让用户逐项确认。

8. 动态项目状态：公开 GitHub 项目顶部放 stars/forks/issues/last commit/license 徽章；有增长叙事时补 Star History。

9. Troubleshooting 表格：至少 3 条，解决用户放弃的最后一公里。

让人想装的写作要领：

• 短句。每个 idea 一行，不要堆在同一段。
• 具体胜于抽象。"36k+ GitHub Stars、900 万/月 npm 下载" 比 "流行的开源项目" 有说服力。
• 让用户想象"用了之后"的场景，而不是描述技术实现。
• 风险或限制放最后，不要一开始就说"注意：这个需要..."。

README 小白友好度检查

发布前逐项核对：

• [ ] 第一句话是痛点，不是功能描述
• [ ] 有"用了之后"的具体场景描述
• [ ] 安装命令一行搞定，放在显眼位置
• [ ] Web 项目有首屏产品截图，生成类项目有代表性输出样例
• [ ] GitHub 项目顶部有动态徽章，公开项目有 Star History 或 repo 活跃度入口
• [ ] Web 项目有自动截图命令，截图在 docs/assets/
• [ ] 前置条件用 checkbox 格式，每条说明怎么安装
• [ ] 使用示例是用户真实会说的话，不是技术命令
• [ ] 有 Troubleshooting 表格（问题 → 解决方法）

README 常见坏味道（避免）

• ❌ 直接把 SKILL.md 的 AI 指令（Output Formatting Rules、Rule:...）放进 README
• ❌ 第一段全是技术描述，没有用户能感受到的价值
• ❌ "基于 arXiv:XXXX..." 开头 — 用户不在乎论文，在乎结果
• ❌ 前置要求放开头，吓跑用户
• ❌ 安装步骤超过 3 步（如果超过了，说明你没想清楚怎么简化）
• ❌ 没有 Troubleshooting，用户遇到问题只能自己摸索
• ❌ Web 项目没有截图，或者截图过期、无法复现
• ❌ Deploy 按钮仍指向 your-org/your-repo 这类占位 URL

发布工作流

1. 读取 SKILL.md，理解 skill 的功能和目标用户
2. 判断语言：默认中文，只在明确国际化需求时写双语
3. 检查 README.md 是否存在，若存在则评估吸引力（不只是完整度）
4. 若 README 不够吸引人，先重写再发布
5. README 确认后，再运行发布脚本
6. 如果当前仓库已有 `origin`，确认脚本使用的是 `origin` 仓库名；否则用 `--repo-name` 明确指定
7. 发布后必须验证 `npx skills add <user>/<repo> --list`，并尽量做临时目录真实安装

发布完成后

向用户展示：

• GitHub 仓库 URL
• 安装命令：npx skills add <user>/<skill-name>
• 验证结果