---
id: sm-skill-publisher
name: "skill-publisher"
url: https://skills.yangsir.net/skill/sm-skill-publisher
author: joeseesun
domain: ai-skill-platform-ecosystem
tags: ["ai-agent-development", "skill-deployment", "platform-integration", "api-publishing", "devops-for-ai"]
install_count: 264
rating: 4.10 (59 reviews)
github: https://github.com/joeseesun/skill-publisher
---

# skill-publisher

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

**Stats**: 264 installs · 4.1/5 (59 reviews)

## Before / After 对比

### 一键发布Claude Code技能至GitHub

## Readme

# skill-publisher

# 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

### 脚本自动完成的步骤

- **验证** 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-run

```

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

**脚本只在 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>`

- 验证结果

Weekly Installs207Repository[joeseesun/skill…ublisher](https://github.com/joeseesun/skill-publisher)GitHub Stars20First Seen12 days agoSecurity Audits[Gen Agent Trust HubFail](/joeseesun/skill-publisher/skill-publisher/security/agent-trust-hub)[SocketPass](/joeseesun/skill-publisher/skill-publisher/security/socket)[SnykPass](/joeseesun/skill-publisher/skill-publisher/security/snyk)Installed oncodex199opencode199cursor199kimi-cli198gemini-cli198amp198

---
*Source: https://skills.yangsir.net/skill/sm-skill-publisher*
*Markdown mirror: https://skills.yangsir.net/api/skill/sm-skill-publisher/markdown*