gh コマンドでエージェントスキルをインストール・管理できるようになった

コーディングエージェント時代にエージェントスキルをチームで共有することの重要性は広く認識されてきました。個人の試行錯誤で生まれたプラクティスをチーム全体で共有し再利用することは、開発速度の向上や品質の安定化に大きく寄与します。またエージェントスキルという文書化を伴う形で暗黙知の形式知化が促進されることも、チームのナレッジマネジメントの観点から重要です。

スキルを共有・配布するための方法としては Vercel が提供する npx skills が広く使われていました。これは GitHub 上で公開されているスキルを npx skills add owner/repo コマンド 1 つでインストールできるというもので、コーディングエージェントごとの差異を吸収してくれることもあり非常に便利なツールでした。

そんななか、GitHub CLI の v2.90.0 から gh skill コマンドが追加され、GitHub 上のエージェントスキルを簡単にインストール・検索・管理できるようになりました。サードパーティーツールに頼らずに、ネイティブな GitHub CLI でスキル管理が完結するようになったことに意義があります。特に gh skill コマンドで GitHub プリミティブ（タグやリリース）を活用してサプライチェーン攻撃に対するリスクを軽減できる点が特徴の 1 つです。

Vercel の npx skills と GitHub CLI の gh skill はどちらも Agent Skills 仕様 に準拠しているため、両者の間でスキルの互換性があります。すでに npx skills を使用してスキルを配布している場合でも、gh skill に移行することは比較的容易でしょう。

この記事では gh skill コマンドの使い方について紹介します。

gh skill コマンドの使い方

gh skill コマンドを使用するためには、まず GitHub CLI を v2.90.0 以降にアップデートする必要があります。gh コマンドのバージョンを確認しておきましょう。

$ brew upgrade gh
$ gh --version
 
gh version 2.90.0 (2026-04-16)
https://github.com/cli/cli/releases/tag/v2.90.0

gh skill コマンドは以下のサブコマンドを提供しています。

スキルをインストールする

スキルを検索する

それでは gh skill コマンドを使ってスキルをインストールしてみましょう。GitHub 上で公開されているスキルを探すには gh skill search コマンドが使用できます。もしくは skills.sh のようなスキルカタログサイトを参照しても良いでしょう。ここでは例として React に関するスキルを検索してみます。

gh skill search react

上記のコマンドを実行すると、GitHub Code Search API を通じて公開リポジトリ全体から、スキル名や説明に "react" というキーワードを含む SKILL.md が検索されます。検索結果からそのままチェックを入れてインストールできます。

スキルの内容を確認する

ここでは https://github.com/vercel-labs/next-skills で公開されている next-best-practices スキルをインストールしてみましょう。ところで第三者が公開しているスキルをインストールする際には、セキュリティの観点からそのスキルの内容をあらかじめ確認しておくことが重要です。スキルの内容が AI の動作を意図しない方向に誘導するような指示を含んでいるプロンプトインジェクションのリスクや、付随するスクリプトがマルウェアであるリスクなどが考えられるためです。

そこで gh skill preview コマンドを使用すれば、インストール前にスキルの内容を安全に確認できます。

# next-best-practices スキルの内容を確認する
gh skill preview vercel-labs/next-skills next-best-practices
# スキル名を選択せずにすべてのスキル一覧から開始することも可能
gh skill preview vercel-labs/next-skills

以下のようにスキルが提供するファイルの一覧が表示され、Enter キーで選択するとその内容を確認できます。

スキルをインストールする

スキルの内容が問題ないことを確認できたら、gh skill install コマンドでインストールします。

gh skill install vercel-labs/next-skills next-best-practices

上記のコマンドを実行すると、GitHub 上の vercel-labs/next-skills レポジトリに公開されている next-best-practices スキルがインストールされます。スキルのバージョンを指定したい場合は、@ に続けてタグやコミットハッシュを指定できます。サプライチェーン攻撃のリスクを軽減するためには、特定のバージョンを指定してインストールすることが推奨されます。

ただし GitHub 上のタグは Immutable Release が設定されていない限り後から変更される可能性があるため、コミットハッシュを指定する方がより安全でしょう。このあたりのセキュリティ上のプラクティスは GitHub Actions などでのサプライチェーン攻撃対策と通じるものがありますね。ここで @<ref> はインストール時に取得するタグやコミットハッシュを指定するための記法で、--pin はインストール後に gh skill update コマンドで更新されないよう固定するためのオプションです。

# コミットハッシュを指定してインストール
gh skill install vercel-labs/next-skills next-best-practices@038954e07bfc313e97fa5f6ff7caf87226e4a782
# pin オプションを使用して、後から更新されないようにする
gh skill install vercel-labs/next-skills next-best-practices --pin 038954e07bfc313e97fa5f6ff7caf87226e4a782

コマンドを実行すると、対話形式でインストールが進行します。

1. どの AI エージェントにスキルをインストールするか

• GitHub Copilot
• Claude Code
• Cursor
• Codex
• Gemini CLI
• Antigravity

2. スキルのスコープ（プロジェクト or ユーザー）

スコープはチームで共有したい場合はプロジェクトスコープ、個人ツールとして使いたい場合はユーザースコープを選択すると良いでしょう。特にチーム開発ではプロジェクトスコープを選択することで、リポジトリにスキルを紐づけて管理できるようになるため便利です。

スキルのインストールが完了すると、選択した AI エージェントに応じたディレクトリにスキルが保存されます。ここでは Claude Code を選択したので、.claude/skills/next-best-practices ディレクトリにスキルがインストールされました。

$ tree .claude/skills/next-best-practices
.claude/skills/next-best-practices
├── SKILL.md
├── async-patterns.md
├── bundling.md
├── data-patterns.md
├── debug-tricks.md
├── directives.md
├── error-handling.md
├── file-conventions.md
├── font.md
├── functions.md
├── hydration-error.md
├── image.md
├── metadata.md
├── parallel-routes.md
├── route-handlers.md
├── rsc-boundaries.md
├── runtime-selection.md
├── scripts.md
├── self-hosting.md
└── suspense-boundaries.md
 
1 directory, 20 files

gh skill コマンドでインストールしたスキルには、SKILL.md ファイルにどの GitHub レポジトリからインストールしたか、どのバージョンをインストールしたかなどのメタデータが追記されます。このメタデータを参照して gh skill update コマンドでスキルの更新を管理できます。

特に github-tree-sha はタグやコミットハッシュが変わっていなくても、実際のファイル内容が変更されたかどうかを検出できるため、「バージョン番号は変わっていないが中身が差し替えられていた」というケースを見逃さずに済みます。

---
description: Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling
metadata:
  github-path: skills/next-best-practices
  github-pinned: 038954e07bfc313e97fa5f6ff7caf87226e4a782
  github-ref: 038954e07bfc313e97fa5f6ff7caf87226e4a782
  github-repo: https://github.com/vercel-labs/next-skills
  github-tree-sha: ad17eb27952b39a6ab0061bd50e8a2213b63a3ec
name: next-best-practices
user-invocable: false
---
 
# Next.js Best Practices
 
Apply these rules when writing or reviewing Next.js code.
 
<!-- 省略 -->

スキルのアップデート

スキルを最新に保つ仕組みを整えておくこともスキル管理の重要なポイントです。例えばライブラリの破壊的な変更があったのにも関わらずそのライブラリに関するスキルが更新されていないといったことがあると、エージェントが古いプラクティスに基づいて行動してしまうことになります。

gh skill コマンドでインストールしたスキルは、gh skill update コマンドで最新バージョンに更新できます。

コマンドを実行すると手元にインストールされているスキルの一覧に対して、更新可能なスキルがあるかどうか確認が行われます。GitHub レポジトリで管理されていないスキル（metadata.github-repo が存在しないスキル）についても、取り込み元の GitHub レポジトリを尋ねる仕様となっています。

$ gh skill update
 
! .system/skill-creator has no GitHub metadata
? Repository for .system/skill-creator (owner/repo):

スキルの内容に更新があった場合には、前後のコミットハッシュが表示され、更新するかどうかの確認が行われます。前述の通り、--pin オプションを使用してインストールしたスキルは確認がスキップされます。

? Repository for .system/skill-creator (owner/repo):
  Skipping .system/skill-creator
⊘ next-best-practices is pinned to 038954e07bfc313e97fa5f6ff7caf87226e4a782 (skipped)
 
2 update(s) available:
  • integrate-context-matic (github/awesome-copilot) 7095ef41 > 86cfeb1c [main]
  • next-best-practices (vercel-labs/next-skills) 0b069c12 > ad17eb27 [main]
 
? Update 2 skill(s)? (Y/n)

特定のスキルだけを更新したい場合は、スキル名を指定できます。

gh skill update next-best-practices

--dry-run オプションを使用すれば、実際には更新せずにどのスキルが更新可能かを確認できます。

gh skill update --dry-run

スキルの公開

スキルを GitHub 上で公開するために必ずしも gh skill publish コマンドを使用する必要はありません。単にスキル仕様に従ったコンテンツを GitHub レポジトリに配置すれば、gh skill install コマンドでインストールできるようになるためです。しかし gh skill publish コマンドを使用すれば、以下のことを自動的に行ってくれるためサプライチェーン攻撃を防止する観点からは推奨されます。

• スキル仕様に従ったバリデーションの実行
• タグの保護やシークレットスキャンニングといったレポジトリ設定のチェック

実際にゼロからレポジトリを作成してスキルを公開する手順を試してみましょう。あらかじめ公開レポジトリを作成しておいてください。

gh repo create my-skill-repo --public

続いてレポジトリ上にスキルを追加します。gh skill コマンドでは以下の場所に配置されているファイルがスキルとして認識されます。

• skills/*/SKILL.md
• skills/{scope}/*/SKILL.md
• */SKILL.md (root-level)
• plugins/{scope}/skills/*/SKILL.md

技術記事をレビューする tech-review スキルを作成してみましょう。スキル名とディレクトリの名前は同じである必要があるため、skills/tech-review/SKILL.md というパスに SKILL.md ファイルを配置します。

---
name: tech-review
description: ソフトウェアエンジニア向けの技術書・原稿をレビューし、構成・技術的正確性・読者体験の観点から改善提案を行うスキル。ユーザーが技術書の原稿、章のドラフト、チュートリアル記事、技術ドキュメントのレビューを依頼したときに使う。「原稿をレビューして」「この章を見てほしい」「技術書を書いている」「コードサンプルをチェックして」「構成についてアドバイスがほしい」といった依頼で発動する。技術書の執筆支援、編集フィードバック、構成改善、コードレビュー（書籍内のコード）、読者レベルの調整など、技術書制作に関わるあらゆるレビュー作業に対応する。
---
 
# 技術書原稿レビュースキル
 
...

gh skill publish コマンドを実行する前に --dry-run オプションを使用して、スキルの内容に問題がないかどうか確認してみましょう。Agent Skills 仕様に準拠していない場合には、エラーが表示されます。例えば以下のような観点がチェックされます。

• name フィールド仕様に準拠しているか（小文字の英数字とハイフンのみ、先頭と末尾は英数字、3 文字以上）
• スキル名とディレクトリ名が一致しているか
• name と description フィールドが存在するか
• allowed-tools フィールドが存在する場合、文字列になっているか（配列は不可）
• metadata.github-* フィールドが含まれていないかどうか（これらは gh skill install によって付与されるインストールメタデータであり、公開時には除外されるべきため）

試しに description フィールドを削除した状態で gh skill publish --dry-run コマンドを実行してみましょう。以下のようなエラーが表示されるはずです。

$  gh skill publish --dry-run
X tech-review: missing required field: description
! tech-review: recommended field missing: license
! no active tag protection rulesets found. Consider protecting tags to ensure immutable releases (Settings > Rules > Rulesets)
 
1 error(s), 2 warning(s)
validation failed with 1 error(s)

description フィールドが存在しないというエラーが表示されました。エラーが存在する限り --dry-run オプションを外して実行したとしても、スキルは公開できません。その他にも以下の 2 つの警告も表示されています。レポジトリの安全性や信頼性を高めるためには、これらの警告も解消しておくことが推奨されます。

• license フィールドが存在しない
• タグの保護ルールが設定されていない

description フィールドを追加して再度 gh skill publish --dry-run コマンドを実行してみましょう。今度はエラーがなく、「Ready to publish!」というメッセージが表示されるはずです。

$ gh skill publish --dry-run
! tech-review: recommended field missing: license
! no active tag protection rulesets found. Consider protecting tags to ensure immutable releases (Settings > Rules > Rulesets)
 
2 warning(s)
 
Ready to publish! Repository: azukiazusa1/my-skill-repo
 
Dry run complete. Use without --dry-run to publish.

エラーが解消されたのでスキルを公開しましょう。まずはリモートレポジトリに変更をプッシュします。

git add skills/tech-review/SKILL.md
git commit -m "Add tech-review skill"
git push origin main

リモートレポジトリに変更をプッシュした時点で既に gh skill install コマンドでインストールできるようになっていますが、gh skill publish コマンドを実行することで、タグの付与やリリースの作成など、スキルの公開に必要な一連の作業を自動化できます。--dry-run オプションを外して gh skill publish コマンドを実行してみましょう。対話形式でスキルの公開が進行します。

1. レポジトリのトピックに agent-skills が存在しない場合は、トピックを追加するかどうか
2. タグのストラテジー（Semver かカスタムか）
3. タグのバージョン（v1.0.0）
4. Immutable Release（タグの付け替えを禁止する機能）を有効化するかどうか
5. リリースノートを自動生成するかどうか

$ gh skill publish
 
Publishing to azukiazusa1/my-skill-repo...
 
? Add "agent-skills" topic to azukiazusa1/my-skill-repo? (required for discoverability) Yes
✓ Added "agent-skills" topic
? Tagging strategy: Semver (recommended): v1.0.0
? Version tag [v1.0.0]: v1.0.0
? Enable immutable releases? (prevents tampering with published releases) Yes
? Create release v1.0.0 with auto-generated notes? Yes
✓ Published v1.0.0
✓ Install with: gh skill install azukiazusa1/my-skill-repo
✓ Pin with:     gh skill install azukiazusa1/my-skill-repo <skill> --pin v1.0.0

確かに GitHub 上の azukiazusa1/my-skill-repo レポジトリに v1.0.0 というタグとリリースが作成されていることが確認できます。

実際に公開したスキルがインストールできるかどうかも確認してみましょう。

gh skill install azukiazusa1/my-skill-repo tech-review

まとめ

• gh skill コマンドを使用すれば、GitHub 上のエージェントスキルを簡単にインストール・検索・管理できるようになる
• コミットハッシュやタグを利用してスキルをピン留めできるため、サプライチェーン攻撃のリスクを軽減できる
• gh skill search <keyword> コマンドで GitHub 上のスキルを検索できる
• gh skill install <owner/repo> <skill> コマンドで GitHub 上のスキルをインストールできる
• gh skill preview <owner/repo> <skill> コマンドでインストール前にスキルの内容を確認できる
• gh skill update コマンドでインストールされているスキルに更新があるかどうか確認し、最新バージョンに更新できる
• gh skill publish コマンドでスキルの公開に必要な一連の作業を自動化できる

参考

• Manage agent skills with GitHub CLI - GitHub Changelog
• GitHub CLI | Take GitHub to the command line
• Release GitHub CLI 2.90.0 · cli/cli
• Overview - Agent Skills