Skill Publisher
一键将 Claude Code Skill 发布到 GitHub，自动完成验证、补全、推送全流程。
前置条件
ghCLI 已安装且已登录（gh auth status）- Skill 目录包含有效的
SKILL.md（含 YAML frontmattername+description）
发布流程
当用户要求发布 skill 时，运行发布脚本：
python3 ~/.claude/skills/skill-publisher/scripts/publish_skill.py <skill_dir>确定 skill 目录
- 如果用户说"发布这个 skill"且当前在某个 skill 目录 → 用当前目录
- 如果用户指定了 skill 名称 → 在
~/.claude/skills/下查找 - 如果不确定 → 问用户要发布哪个 skill
脚本自动完成的步骤
- 验证 SKILL.md 的 YAML frontmatter（name + description）
- 检查 gh CLI 就绪状态
- 创建 LICENSE（MIT，如果缺少）
- 生成 README.md（从 SKILL.md 提取，如果缺少）
- 初始化 git（如果需要）
- 创建 GitHub 公开仓库并推送
- 验证
npx skills add可发现
参数选项
| 参数 | 说明 |
|---|---|
--private | 创建私有仓库（默认公开） |
--dry-run | 仅检查，不实际发布 |
--skip-verify | 跳过 npx skills 验证 |
--github-user USER | 指定 GitHub 用户名（默认自动获取） |
--no-symlink | 跳过创建 ~/.agents/skills/ symlink |
自动创建 ~/.agents/skills/ Symlink
发布成功后，脚本自动在 ~/.agents/skills/<name> 创建指向 skill 目录的 symlink。
这个目录是通用 Agent Skills 标准目录，以下工具会自动读取： OpenCode、Codex CLI、Cursor、Gemini CLI、GitHub Copilot、Amp、Cline、Warp 等。
一次发布，多工具共享，无需重复配置。
⚠️ 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 ~/.claude/skills/skill-publisher/scripts/publish_skill.py ~/.claude/skills/yt-search-download
用户：把当前 skill 发到 GitHub
执行：python3 ~/.claude/skills/skill-publisher/scripts/publish_skill.py .
用户：先检查一下能不能发布
执行：python3 ~/.claude/skills/skill-publisher/scripts/publish_skill.py <dir> --dry-runREADME 质量检查（发布前必做）
脚本只在 README 不存在时自动生成一个基础模板。发布前，必须人工检查/撰写 README，确保它对陌生用户有价值。
README 必须包含的 7 个要素
- 价值主张（Hook）：第一段就让用户明白"这能解决我什么问题"，用具体场景描述，避免抽象描述
- 前置条件清单（checkbox 格式）：用
- []列出所有依赖，让用户逐一确认。每条都要写清楚怎么装，不能只说"需要 xxx" - 完整安装步骤：编号步骤，细到小白能跟着做。每步都提供验证命令（如
--version） - 自然语言使用示例：展示 2-3 个用户会真实说出的句子，让人一眼看懂怎么触发
- 致谢原作者：如果 skill 基于第三方工具/库，必须注明原项目链接和作者
- 必要的风险/限制说明：写操作、账号相关、费用相关的风险需明确告知
- 常见问题/Troubleshooting：至少列出 3 个常见报错和解决方法，降低用户放弃率
双语判断原则
判断是否需要中英双语 README：
需要双语的信号（满足任一即应写双语）：
- Skill 的核心功能面向国际平台（Twitter、YouTube、Reddit、GitHub、HackerNews 等）
- SKILL.md 的 description 包含英文触发词
- 底层工具是英文开源项目，原作者是海外用户
- 技术命令本身是英文（如 CLI 工具）
双语结构建议：
# skill-name
> One-line English description
> 中文一行描述
**[English](#english) | [中文](#中文)**
---
<a name="english"></a>
## English
[完整英文内容]
---
<a name="中文"></a>
## 中文
[完整中文内容]README 小白友好度检查
发布前逐项核对：
- 前置条件用 checkbox 格式列出，每条说明怎么安装
- 安装步骤有编号，每步有验证命令
- 使用示例是用户真实会说的话，不是技术命令
- 有 Troubleshooting 表格（问题 → 解决方法）
- 没有让用户"自行参考文档"而不给具体命令
- 跨平台差异有说明（如 macOS/Windows 路径不同）
README 常见坏味道（避免）
- ❌ 直接把 SKILL.md 的 AI 指令（Output Formatting Rules、Rule:...）放进 README
- ❌ 第一段全是技术描述，没有用户能感受到的价值
- ❌ 前置要求写得模糊（如"需要 Chrome 扩展"但不说怎么装）
- ❌ 基于别人的项目但没有致谢
- ❌ 没有 Troubleshooting，用户遇到问题只能自己摸索
- ❌ 纯中文 README 但 skill 明显有国际用户群
发布工作流
1. 读取 SKILL.md，理解 skill 的功能和目标用户
2. 判断是否需要双语（参考双语判断原则）
3. 检查 README.md 是否存在，若存在则评估质量
4. 若 README 质量不达标（缺少上述要素），先重写 README
5. README 确认后，再运行发布脚本发布完成后
向用户展示：
- GitHub 仓库 URL
- 安装命令：
npx skills add <user>/<skill-name> - 验证结果