✏️

gh skill を自分の言葉で説明できるようにしてみた — Agent Skill 管理がパッケージマネージャ級になる日

2026/04/20に公開

GitHub

skill

tech

!本記事は、AI との対話で構成とドラフトを作ったあと、自分で公式ドキュメントを読みながら検証・追記・書き直しを行いました。
2026-04-16、GitHub CLI に gh skill という新しいサブコマンドが追加されました。
公式の発表はこれです。
https://x.com/GHchangelog/status/2044834471527027143
Agent Skills を日常的に触っている身としては見過ごせないアップデートなので、自分の理解を整理する意味でこの記事を書いています。公式の Changelog と Agent Skills Specification、それから cli/cli v2.90.0 リリース を行ったり来たりしながら読み解いていったので、そのときの頭の中を再現しつつ、学んだログとして残しておきます。
結論から言うと、gh skill は「Skill のライフサイクルをまるごとパッケージマネージャ体験に引き上げる」ツールで、配布経路の安心感が npm や apt のそれに近づいたなと思っています。

 そもそも Agent Skills って何だっけ話を始める前に、Agent Skills そのものをおさらいしておきます。
Agent Skills は、AI エージェント共通の「命令書フォーマット」です。Claude Code / Cursor / Codex / GitHub Copilot / Gemini CLI / Antigravity といった複数のエージェントが、同じ仕様でこの命令書を読めるようになっています。仕様は独立団体 agentskills.io が公開しています。
ディレクトリ構造はこんな感じ。
skill-name/
├── SKILL.md          # 必須。frontmatter + Markdown 本文
├── scripts/          # 任意。エージェントが実行するコード
├── references/       # 任意。詳細ドキュメント(オンデマンド読み込み)
└── assets/           # 任意。テンプレート・画像などの静的資源
SKILL.md の frontmatter には制約があります。


フィールド
必須
制約


name
✅
64 字以内、a-z と - のみ、親ディレクトリ名と一致

description
✅
1024 字以内、「何をして・いつ使うか」を書く

license

ライセンス名または LICENSE ファイル名

compatibility

500 字以内、環境要件(OS, 依存パッケージ等)

metadata

自由な key-value。クライアント固有の拡張情報用

allowed-tools

事前承認したツール(実験的機能)


 gh skill は、何を 1 コマンドにまとめたのかここから本題です。
gh skill は GitHub CLI v2.90.0 で追加された新サブコマンドで、これまでバラバラだった Skill のライフサイクルを、gh ひとつから扱えるようにまとめたものです。位置づけとしては、Skill エコシステムにおける npm や apt と考えると一番しっくりくる感じがします。
役割を抽象化すると 3 本柱になります。

インストール — リポジトリを指定するだけで配布。バージョン・コミット SHA による固定、エージェント先の指定が可能

更新 — 全エージェントホスト横断の一括最新化

公開 — 仕様バリデーション + GitHub リリース化

 サブコマンド 5 つの役割分担gh skill --help で見られるサブコマンドは 5 つ。それぞれが Skill ライフサイクルの 1 工程を担っています。

search — GitHub 上に公開されている Skill を検索

preview — インストール前に SKILL.md の中身を確認

install — ローカルにインストール

update — インストール済みを一括最新化

publish — 仕様バリデーション + GitHub リリース化

 preview が結構大事かも?Changelog を読んでいて、ページ末尾の Editor's note にこう書かれていたのが引っかかりました。
Skills are installed at your own discretion. They are not verified by GitHub and may contain prompt injections, hidden instructions, or malicious scripts. We strongly recommend inspecting the content of skills before installation, which can be done via the gh skill preview command.
— GitHub Changelog (2026-04-16)
要約すると「GitHub は Skill の中身を検証していない」と。考えてみれば当然で、SKILL.md はそれ自体が AI への命令書なので、悪意ある命令が混ざっていれば AI レベルで実行されてしまいます。GitHub は配布経路(タグ・リリース・アクセス制御)までしか守れないんですね。
つまり、gh skill の 5 コマンドの中で「検証だけは人間がやるしかない」わけで、その目視チェックを支えるのが preview ということになります。
# インストールせず中身だけ確認
gh skill preview OWNER/REPO
このコマンド、確認ダイアログを進めると SKILL.md の中身だけが表示されます。この時点ではまだインストールされないので、安全に中身をレビューできます。
運用としては、毎回手動で全文読むのも現実的じゃないので、読んだ中身を別の Skill でチェックする「メタ Skill」 を自分で書いて回す、みたいな発想も湧いてきました。

 install / update を触ってみる次に触ったのが install と update。こちらもコマンド自体はシンプルです。

 install は純正ディレクトリに直接コピーする# 最新タグで導入
gh skill install OWNER/REPO

# タグで完全固定
gh skill install OWNER/REPO SKILL --pin v1.2.0

# コミット SHA で完全固定(最大の再現性)
gh skill install OWNER/REPO SKILL --pin abc123def

# エージェント先とスコープを指定
gh skill install OWNER/REPO SKILL --agent claude-code --scope user
--agent で配置先を選べます。Claude Code / Cursor / Codex / Copilot / Gemini CLI / Antigravity に対応しています。Claude Code 向けなら ~/.claude/skills/SKILL_NAME/ に実ファイルが直接コピー配置される仕組み。
ここが既存の npm ベースの Skill 配布と思想的に違うなと思いました。gh skill は各エージェント純正ディレクトリに独立したコピーを置く。Skill そのものを「npm パッケージ」ではなく「各エージェント自前の資産」として扱う思想、という感じです。

 update は普通に使えてシンプル# 対話的に 1 つずつ確認
gh skill update

# プロンプトなしで全部
gh skill update --all

# 差分チェックだけ(実ファイルは書き換えない)
gh skill update --dry-run
--dry-run で差分だけ見られるのが地味に便利。CI とかで「更新あるか確認だけしておきたい」シーンで使えそう。

 publish を試す自分の Skill を公開する側に回ると、今度は publish が出てきます。
# バリデーションのみ
gh skill publish

# メタデータ問題を自動修正
gh skill publish --fix
このコマンドが検証してくれるのは、Skill 本体の命名規則と frontmatter 必須項目のチェックあたり。--fix を付けると自動修正できる項目もあって、僕は試してみて name の表記揺れ(MY-Skill → my-skill)が自動で直ったのが地味に助かりました。最初の通過儀礼としてはだいぶ楽。
ちなみに cli/cli v2.90.0 のリリースノート を見ると、この publish には「未プッシュのコミットを自動で push してから publish する」挙動も組み込まれています(PR #13171)。細かい配慮だけど、これをやってないと「ローカルでは動いたのに publish 先のリリースに反映されない」みたいな罠を踏みがちなので、かなり実戦寄りの設計だなと。

 既存の Skill 配布方法との違いここまで読んで、「じゃあ今まで使ってきた npm ベースの Skill 配布からどう乗り換えればいい?」という話になります。



これまで(npm 配布系)
これから(gh skill)


配置先
単一の source of truth を各エージェントが symlink で参照
エージェント純正ディレクトリに実ファイルコピー

配布経路
npm パッケージとして提供
GitHub Releases + gh CLI 統合

「配置先」の違いは好み次第。symlink 方式は "単一 source of truth" で編集が楽というメリットもあります。ただ gh skill 方式は「各エージェントがそれぞれ自分の領分を持つ」ので、片方の環境を壊してももう片方は無事、という独立性が担保されるのが嬉しいポイント。
「配布経路」は GitHub Releases に統合されたことで、gh コマンドで普通に扱えるようになったのが大きいかなと。既に gh CLI を日常的に使ってるなら、学習コストがほぼゼロで入ってきます。

 明日から試す 3 ステップこの記事の締めくくりに、自分が明日試すつもりのチェックリストを置いておきます。
Step 1: 環境準備
gh --version    # 2.90.0 以上であることを確認
brew upgrade gh # 足りなければ更新
Step 2: 仕様チェック
cd path/to/my-skill
gh skill publish --fix
# 命名規則や frontmatter 違反を自動修正
# 残る警告はターミナル表示に従って手動修正
Step 3: 初公開
gh skill publish
# 対話形式で v1.0.0 タグ付き初公開
テスト用リポジトリで試してから本番に進めば、手元で試行錯誤しても事故りにくいはず。

 まとめとこれからgh skill を一通り調べてみて、「Skill エコシステムのパッケージマネージャ」という位置づけが一番しっくりきました。配布経路や仕様バリデーションが標準化されるほど、Skill の中身(＝ AI への命令)そのものに集中できるようになる、というのは個人的に嬉しい流れです。
次は自分の手元の Skill 群(仕事で作った社内向けのやつ)を gh skill publish で一通り通してみて、命名規則や description の書き直しがどれくらい必要か?などを、実測していくつもり。

 参考
Manage agent skills with GitHub CLI — GitHub Changelog / 2026-04-16

GitHub Changelog on X (2026-04-16) — 公式アナウンス投稿

Agent Skills Specification — agentskills.io

GitHub CLI v2.90.0 Release — cli/cli

gh_skill manual — cli.github.com

フィールド	必須	制約
`name`	✅	64 字以内、`a-z` と `-` のみ、親ディレクトリ名と一致
`description`	✅	1024 字以内、「何をして・いつ使うか」を書く
`license`		ライセンス名または LICENSE ファイル名
`compatibility`		500 字以内、環境要件(OS, 依存パッケージ等)
`metadata`		自由な key-value。クライアント固有の拡張情報用
`allowed-tools`		事前承認したツール(実験的機能)

	これまで(npm 配布系)	これから(gh skill)
配置先	単一の source of truth を各エージェントが symlink で参照	エージェント純正ディレクトリに実ファイルコピー
配布経路	npm パッケージとして提供	GitHub Releases + `gh` CLI 統合

そもそも Agent Skills って何だっけ

gh skill は、何を 1 コマンドにまとめたのか

サブコマンド 5 つの役割分担

preview が結構大事かも?

install / update を触ってみる

install は純正ディレクトリに直接コピーする

update は普通に使えてシンプル

publish を試す

既存の Skill 配布方法との違い

明日から試す 3 ステップ

まとめとこれから

参考

Discussion