skill-publisher

スキルパブリッシャー

ワンクリックでエージェントスキルを GitHub に公開し、検証、README の品質チェック、補完、プッシュ、実際のインストール検証を自動で行います。

前提条件

• gh CLI がインストールされ、ログイン済みであること（gh auth status）
• スキルディレクトリに有効な SKILL.md（YAML frontmatter に name と description を含む）があること
• 正式なソースディレクトリとして /Users/joe/.agents/skills/<name> を優先してください。.codex / .claude は互換性のあるエントリーポイントとして使用できます。

公開の流れ

ユーザーからスキルの公開を依頼されたら、公開スクリプトを実行します。

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

スキルディレクトリの決定

• ユーザーが「このスキルを公開して」と言い、現在いる場所がスキルディレクトリの場合 → 現在のディレクトリを使用
• ユーザーがスキル名を指定した場合 → まず ~/.agents/skills/ 以下を検索
• 判断できない場合 → どのスキルを公開するかユーザーに尋ねる

スクリプトが自動で行う手順

1. 検証：SKILL.md の YAML frontmatter（name + description）
2. 確認：gh CLI の準備状況
3. 作成：LICENSE（ない場合は MIT）
4. 生成または確認：README.md。生成時に TODO テンプレートは使用せず、既存の場合は明らかなプレースホルダーを検出
5. リポジトリ名の特定：現在の origin リポジトリ名を優先して使用し、skill-publisher を誤ったリポジトリに公開するのを防止
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 リポジトリ名を優先し、それがない場合はスキル名を使用
--no-symlink	~/.agents/skills/ への実体ディレクトリの同期をスキップ

~/.agents/skills/ 実体ディレクトリへの自動同期

公開が成功すると、スクリプトはスキルを ~/.agents/skills/<name> に実体ディレクトリとして自動同期できます。

このディレクトリは汎用 Agent Skills 標準ディレクトリで、以下のツールが自動的に読み込みます。 OpenCode、Codex CLI、Cursor、Gemini CLI、GitHub Copilot、Amp、Cline、Warp など。

一度公開すれば、複数のツールで共有でき、設定を繰り返す必要はありません。

現在の公開元がすでに ~/.agents/skills/<name> の場合、スクリプトはソースディレクトリを誤って削除しないよう、同期をスキップします。スキル名とリポジトリ名が異なる場合や、ローカルコピーを作成したくない場合は、公開時に --no-symlink を追加してください。

⚠️ SKILL.md YAML の安全ルール（公開前に必ず確認）

npx skills は厳格な YAML パーサーを使用するため、以下の書き方ではインストールに失敗します（「No valid skills found」と表示されます）。

❌ 誤った書き方	✅ 正しい書き方
description: 含有 "引号" 的文字	| ブロックスカラーに変更（下記参照）
description: 含单引号'的文字	| ブロックスカラーに変更
description: 含冒号: 的文字	| ブロックスカラーに変更

最も安全な description の書き方：

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

スクリプトには YAML の厳格な検証（pyyaml）が組み込まれており、公開前にこの種のエラーを検出して修正方法を提示します。

公開済みスキルの更新

GitHub リポジトリがすでに存在するスキルに対して同じコマンドを再実行すると、スクリプトがリポジトリの存在を検出し、更新を自動で 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. ファーストビューでの証拠：製品のスクリーンショット、出力例、実際に生成された成果物、または短いデモを README の最初の画面付近に掲載してください。Web プロジェクトでは、製品全体のスクリーンショットを優先してください
3. 動的な信頼シグナル：GitHub stars、forks、issues、last commit、license、deploy/install ボタンなどのバッジをページ上部に配置してください。一般公開に適したプロジェクトには Star History を追加してください
4. 前提条件の一覧（チェックボックス形式）：- [ ] を使ってすべての依存関係を列挙し、ユーザーが一つずつ確認できるようにします。それぞれのインストール方法を明記し、「xxx が必要」とだけ書かないでください
5. 完全なインストール手順：初心者でも実行できるよう、番号付きの手順で詳しく説明します。各手順に検証用コマンド（--version など）を記載してください
6. 自然言語での使用例：ユーザーが実際に言いそうな文を 2～3 個示し、どのように起動するかすぐに分かるようにします
7. 元の作者への謝辞：スキルがサードパーティのツールやライブラリに基づいている場合、元のプロジェクトへのリンクと作者を必ず記載してください
8. 必要なリスク・制限事項の説明：書き込み操作、アカウント、費用に関するリスクを明確に伝えてください
9. よくある質問・トラブルシューティング：よくあるエラーとその解決方法を少なくとも 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、ビルド状況（ある場合）
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 用スクリーンショットの生成を優先してください
• スクリーンショットスクリプトで、たとえば SCREENSHOT_URL=http://127.0.0.1:3000 npm run capture:screenshots のように、環境変数で URL を指定できるようにしてください
• スクリーンショットファイルは 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>
• 验证结果