Skill Publisher

一键将 Claude Code Skill 发布到 GitHub，自动完成验证、补全、推送全流程。

前置条件

• gh CLI 已安装且已登录（gh auth status）
• Skill 目录包含有效的 SKILL.md（含 YAML frontmatter name + description）

发布流程

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

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

确定 skill 目录

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

脚本自动完成的步骤

1. 验证 SKILL.md 的 YAML frontmatter（name + description）
2. 检查 gh CLI 就绪状态
3. 创建 LICENSE（MIT，如果缺少）
4. 生成 README.md（从 SKILL.md 提取，如果缺少）
5. 初始化 git（如果需要）
6. 创建 GitHub 公开仓库并推送
7. 验证 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-run

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

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

README 必须包含的 7 个要素

1. 价值主张（Hook）：第一段就让用户明白"这能解决我什么问题"，用具体场景描述，避免抽象描述
2. 前置条件清单（checkbox 格式）：用 - [ ] 列出所有依赖，让用户逐一确认。每条都要写清楚怎么装，不能只说"需要 xxx"
3. 完整安装步骤：编号步骤，细到小白能跟着做。每步都提供验证命令（如 --version）
4. 自然语言使用示例：展示 2-3 个用户会真实说出的句子，让人一眼看懂怎么触发
5. 致谢原作者：如果 skill 基于第三方工具/库，必须注明原项目链接和作者
6. 必要的风险/限制说明：写操作、账号相关、费用相关的风险需明确告知
7. 常见问题/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>
• 验证结果