先日、GitHub CLIに gh skill コマンドが追加されました。

　
SKILL.mdのフロントマターにインストールした時の情報が載せられることから良さそうと感じました。

一方、自分のローカルで管理しているスキルも扱えないのかなと思って調べたところ、 --from-local が使えそうでした。
https://cli.github.com/manual/gh_skill_install#options

そこで、実際に --from-local などを試してみたことから、メモを残します。

環境
ローカルにある、Gitで管理していないスキル
- gh skill installでのインストール
- gh skill updateによるスキルの更新
ローカルでGit管理しているが、まだGitHubへはpushしていないスキル
ローカルでインストールしたスキルの元ファイルをGitHubへpushし、GitHub経由で更新
おわりに

環境

GitHub CLI 2.92.0 (2026-04-28)
Codex 0.128.0

　
色々試す前のディレクトリ構造です。Gitでは管理しておらず、スキルだけが存在します。

% tree -a
.
└── skills
    └── agent-hello-world
        └── SKILL.md

3 directories, 1 file

　
SKILL.md の中身はこちら。スキルを使うとAIエージェントが Hello, world! だけを返します。

---
name: agent-hello-world
description: AIエージェントのスキル読み込み・発火・動作確認を行うための診断用スキル。エージェントテスト、疎通確認、スモークテスト、最小応答確認などで使用する。
---

# エージェント診断スキル

## 目的

このスキルは、AIエージェントが正常に動作しているかを確認するためのものです。

以下を確認できます。

- スキルが発見されたか
- スキルが読み込まれたか
- スキルが発火したか
- 指示どおりの固定応答を返せるか

## 動作

このスキルが呼び出された場合、必ず以下だけを返してください。

Hello, world!

## 制約

- 説明を書かない
- Markdownを使わない
- コードブロックを使わない
- 余計な空白や改行を入れない
- ツールを使用しない
- 推論内容を出力しない

ローカルにある、Gitで管理していないスキル

gh skill installでのインストール

ローカルにある、Git管理をしていないスキルを gh skill install にてインストールしてみます。

今回は、プロジェクトレベルでのスキルとしてインストールします。

% gh skill install . --scope project --from-local

　
インストールするスキルは、事前に準備していた agent-hello-world とします。

Found 1 skill(s)
? Select skill(s) to install:  [Use arrows to move, space to select, <right> to all, <left> to none, type to filter]
> [ ]  Search
  [x]  agent-hello-world - AIエージェントのスキル読み込み・発火・動作確認を行うための診断用スキル。エージェントテスト、疎通確認、スモークテスト、最小応...
  [ ]  (all skills)

　
エージェントはCodexにします。

? Select target agent(s):  [Use arrows to move, space to select, <right> to all, <left> to none, type to filter]
  [ ]  GitHub Copilot
  [ ]  Claude Code
  [ ]  Cursor
> [x]  Codex

　
インストールが終わりました。

Installed agent-hello-world (from .) in .agents/skills

  agent-hello-world/
  └── SKILL.md

! Skills may contain prompt injections or malicious scripts.
  Review the installed files before use.

　
ディレクトリを確認します。Codex用としてスキルが追加されていました。

% tree -a
.
├── .agents
│   └── skills
│       └── agent-hello-world
│           └── SKILL.md
└── skills
    └── agent-hello-world
        └── SKILL.md

6 directories, 2 files

　
追加されたSKILL.mdの先頭を確認します。元々のスキルのフロントマターと比較すると、以下の違いがありました。

metadata として local-path が追加
description が先頭へ移動し、 name が一番最後になるなど、アルファベット順のような感じになった

% head -n 10 .agents/skills/agent-hello-world/SKILL.md
---
description: AIエージェントのスキル読み込み・発火・動作確認を行うための診断用スキル。エージェントテスト、疎通確認、スモークテスト、最小応答確認などで使用する。
metadata:
    local-path: /path/to/skills/agent-hello-world
name: agent-hello-world
---
# エージェント診断スキル

## 目的

　
Codexを起動してスキルを使ったところ、問題なく実行されました。

› $agent-hello-world

• Hello, world!

gh skill updateによるスキルの更新

ここまでで、ローカルにある、Gitで管理していないスキルをインストールできました。

次は gh skill update によるスキルの更新を試してみます。

準備

Hello, codex! を返すようにスキルを変更します。変更した内容は以下の通りです。

% sed -n '21,23p' ./skills/agent-hello-world/SKILL.md
このスキルが呼び出された場合、必ず以下だけを返してください。

Hello, codex!

　
Codexを停止し、新しいセッションでスキルを使用します。この時点ではまだ古いスキルを参照しています。

› $agent-hello-world

• Hello, world!

gh skill updateでは更新がスキップされた

スキルを指定して gh skill update したところ、複数のスキルが表示されました。今回の環境では .agents と skills の各ディレクトリにあるスキルが検出されたように見えました。

いずれのスキルもスキップされて「All skills are up to date.」となり、スキルの更新は行われませんでした。

% gh skill update agent-hello-world
! agent-hello-world has no GitHub metadata
? Repository for agent-hello-world (owner/repo):
  Skipping agent-hello-world
! agent-hello-world has no GitHub metadata
? Repository for agent-hello-world (owner/repo):
  Skipping agent-hello-world
All skills are up to date.

gh skill installにてスキルを上書き更新する

gh skill update が使えないので、 gh skill install してみます。

すると、 ? Skill "agent-hello-world" already exists. Overwrite? と聞かれました。

そこで、Yes としたところ、スキルの上書きによる更新が行われました。

% gh skill install . --scope project --from-local
Found 1 skill(s)
? Select skill(s) to install: agent-hello-world - AIエージェントのスキル読み込み・発火・動作確認を行うための診断用スキル。エージェントテスト、疎通確認、スモークテスト、最小応...

! Skills are not verified by GitHub and may contain prompt injections, hidden instructions, or malicious scripts. Always review skill contents before use.


? Select target agent(s): Codex
? Skill "agent-hello-world" already exists. Overwrite? Yes
Installed agent-hello-world (from .) in .agents/skills

  agent-hello-world/
  └── SKILL.md

! Skills may contain prompt injections or malicious scripts.
  Review the installed files before use.

　
SKILL.mdファイルを確認したところ、更新後の内容が記載されていました。

% sed -n '22,24p' .agents/skills/agent-hello-world/SKILL.md
このスキルが呼び出された場合、必ず以下だけを返してください。

Hello, codex!

　
また、新しいセッションのCodexでスキルを使ったところ、スキル結果が更新されていました。

› $agent-hello-world

• Hello, codex!

ローカルでGit管理しているが、まだGitHubへはpushしていないスキル

続いて、ローカルでGit管理しているが、まだGitHubへはpushしていないスキルでの挙動を確認します。

準備

まずはローカルファイルをGit管理します。

% git init
% git commit --allow-empty -m "first commit"

　
先ほど作成したスキルのディレクトリや、 gh skill install 先の .agents ディレクトリは、gitignoreしておきます。

% echo ".agents/" >> .gitignore
% echo "skills/agent-hello-world/" >> .gitignore

　
今回インストールするスキルを用意します。先ほどのスキルを流用し、 ./skills/agent-hello-foo/SKILL.md として作成します。

name を変更します。

% sed -n '2p' ./skills/agent-hello-foo/SKILL.md
name: agent-hello-foo

　
応答も Hello, foo! とします。

% sed -n '21,23p' ./skills/agent-hello-foo/SKILL.md
このスキルが呼び出された場合、必ず以下だけを返してください。

Hello, foo!

　
この時点でコミットしておきます。

% git commit -am "add hello-foo skill"

gh skill installでのインストール

GitHubで管理していないため、ローカルからインストールします。

% gh skill install . --scope project --from-local
Found 2 skill(s)
? Select skill(s) to install: agent-hello-foo - AIエージェントのスキル読み込み・発火・動作確認を行うための診断用スキル。エージェントテスト、疎通確認、スモークテスト、最小応...

! Skills are not verified by GitHub and may contain prompt injections, hidden instructions, or malicious scripts. Always review skill contents before use.


? Select target agent(s): Codex
Installed agent-hello-foo (from .) in .agents/skills

  agent-hello-foo/
  └── SKILL.md

! Skills may contain prompt injections or malicious scripts.
  Review the installed files before use.

　
フロントマターを確認します。ローカルでインストールした場合、Gitで管理していても local-path になるようです。

% head -n 5 .agents/skills/agent-hello-foo/SKILL.md
---
description: AIエージェントのスキル読み込み・発火・動作確認を行うための診断用スキル。エージェントテスト、疎通確認、スモークテスト、最小応答確認などで使用する。
metadata:
    local-path: /path/to/skills/agent-hello-foo
name: agent-hello-foo

　
内容も確認します。

% sed -n '22,24p' .agents/skills/agent-hello-foo/SKILL.md
このスキルが呼び出された場合、必ず以下だけを返してください。

Hello, foo!

　
追加されたスキルは問題なく使えました。

› $agent-hello-foo

• Hello, foo!

gh skill updateによるスキルの更新

SKILL.md を更新します。更新した結果は以下の通りです。

% sed -n '21,23p' ./skills/agent-hello-foo/SKILL.md
このスキルが呼び出された場合、必ず以下だけを返してください。

Hello, foo foo!

　
この状態で gh skill update したところ、スキルの更新がスキップされました。

% gh skill update agent-hello-foo
! agent-hello-foo has no GitHub metadata
? Repository for agent-hello-foo (owner/repo):
  Skipping agent-hello-foo
...

gh skill installによるスキルの上書き更新

先ほどと同じように、 gh skill install でスキルを上書きしてみます。

% gh skill install . --scope project --from-local
Found 2 skill(s)
? Select skill(s) to install: agent-hello-foo - AIエージェントのスキル読み込み・発火・動作確認を行うための診断用スキル。エージェントテスト、疎通確認、スモークテスト、最小応...

! Skills are not verified by GitHub and may contain prompt injections, hidden instructions, or malicious scripts. Always review skill contents before use.


? Select target agent(s): Codex
? Skill "agent-hello-foo" already exists. Overwrite? Yes
Installed agent-hello-foo (from .) in .agents/skills

  agent-hello-foo/
  └── SKILL.md

! Skills may contain prompt injections or malicious scripts.

　
ファイルを確認すると、スキルが更新されていました。

% sed -n '22,24p' .agents/skills/agent-hello-foo/SKILL.md
このスキルが呼び出された場合、必ず以下だけを返してください。

Hello, foo foo!

ローカルでインストールしたスキルの元ファイルをGitHubへpushし、GitHub経由で更新

ここで、gh skill install --from-local でインストール済のスキルについて、GitHubへpushしてGitHubからアップデートできるのか気になりました。

そこで今回は、以下の手順で確認することにしました。

準備
- main とは異なるブランチ feature/hello_github （以降は 作業ブランチ と呼ぶ）へ切り替え
- 新しいスキルを追加し、インストール
- GitHubへ作業ブランチをpush
作業ブランチ上でスキルを更新・コミットし、GitHubへpush
作業ブランチを push した状態で GitHub 上のスキルとして認識されるか確認
GitHub上で作業ブランチを main ブランチへマージ
main ブランチへ切り替え、git pullする
main ブランチ上で gh skill update を実行

準備

ブランチを切り替えます。

% git switch -c feature/hello_github

　
Hello, GitHub! を返す、新しいスキルを作ります。

% nl -ba ./skills/agent-hello-github/SKILL.md | sed -n -e '2p' -e '21,23p'
     2  name: agent-hello-github
    21  このスキルが呼び出された場合、必ず以下だけを返してください。
    22
    23  Hello, GitHub!

　
今回はスキル名 agent-hello-github 、および、エージェント名を指定して、対話せずにインストールします。

% gh skill install . agent-hello-github --scope project --agent codex --from-local
Found 3 skill(s)

! Skills are not verified by GitHub and may contain prompt injections, hidden instructions, or malicious scripts. Always review skill contents before use.

Installed agent-hello-github (from .) in .agents/skills

  agent-hello-github/
  └── SKILL.md

! Skills may contain prompt injections or malicious scripts.
  Review the installed files before use.

　
インストール結果を確認します。

% nl -ba .agents/skills/agent-hello-github/SKILL.md | sed -n -e '3,5p' -e '22,24p'
     3  metadata:
     4      local-path: /path/to/skills/agent-hello-github
     5  name: agent-hello-github
    22  このスキルが呼び出された場合、必ず以下だけを返してください。
    23
    24  Hello, GitHub!

　
スキルを使っても想定通りでした。

› $agent-hello-github

• Hello, GitHub!

　
結果は良さそうなのでコミットし、GitHubへpushします。

% git add .

% git commit -m "add hello github skill"

% git push origin feature/hello_github

作業ブランチ上でスキルを更新・コミットし、GitHubへpush

引き続き作業ブランチ上でスキルを更新します。ここでは Hello, GitHub bar! を返すようにします。内容はこんな感じです。

% sed -n '21,23p' ./skills/agent-hello-github/SKILL.md
このスキルが呼び出された場合、必ず以下だけを返してください。

Hello, GitHub bar!

　
スキルの更新元をGitHub経由にできるか確認するため、ブランチ feature/hello_github でコミットしてpushします。

% git commit -am "update hello github skill"

% git push origin feature/hello_github

作業ブランチを push した状態で GitHub 上のスキルとして認識されるか確認

ここで、作業ブランチ上のスキルをGitHub CLIが認識できるか試してみます。

gh skill update agent-hello-github し、途中でリポジトリ名を聞かれたら thinkAmi-sandbox/gh_skill_local-example を入力します。

しかし、default branchである main にはまだ存在しないため、更新ができませんでした。

% gh skill update agent-hello-github
! agent-hello-github has no GitHub metadata
? Repository for agent-hello-github (owner/repo): thinkAmi-sandbox/gh_skill_local-example
! agent-hello-github has no GitHub metadata
? Repository for agent-hello-github (owner/repo): thinkAmi-sandbox/gh_skill_local-example
! Skill agent-hello-github not found in thinkAmi-sandbox/gh_skill_local-example
! Skill agent-hello-github not found in thinkAmi-sandbox/gh_skill_local-example
All skills are up to date.

GitHub上で作業ブランチをmainブランチへマージ

作業ブランチを main ブランチへマージするプルリクを作り、マージします。
https://github.com/thinkAmi-sandbox/gh_skill_local-example/pull/1

これで、今回追加した agent-hello-github スキルが main ブランチに入りました。

mainブランチへ切り替え、git pullする

ローカルにて、GitHub上の main ブランチの中身を取り込みます。

% git switch main

% git pull

mainブランチ上で gh skill update を実行

ローカルの main ブランチ上で gh skill update を実行します。途中のリポジトリ名の入力は thinkAmi-sandbox/gh_skill_local-example とします。

すると更新が見つかり、スキルが更新されました。

% gh skill update agent-hello-github
! agent-hello-github has no GitHub metadata
? Repository for agent-hello-github (owner/repo): thinkAmi-sandbox/gh_skill_local-example
! agent-hello-github has no GitHub metadata
? Repository for agent-hello-github (owner/repo): thinkAmi-sandbox/gh_skill_local-example

2 update(s) available:
  • agent-hello-github (thinkAmi-sandbox/gh_skill_local-example)  > 276630e4 [main]
  • agent-hello-github (thinkAmi-sandbox/gh_skill_local-example)  > 276630e4 [main]

? Update 2 skill(s)? Yes
✓ Updated agent-hello-github
✓ Updated agent-hello-github

　
結果を確認します。

.agents ディレクトリはフロントマターと内容が更新されていました。

% nl -ba .agents/skills/agent-hello-github/SKILL.md | sed -n -e '3,8p' -e '25,27p'
     3  metadata:
     4      github-path: skills/agent-hello-github
     5      github-ref: refs/heads/main
     6      github-repo: https://github.com/thinkAmi-sandbox/gh_skill_local-example
     7      github-tree-sha: 276630e491b53b6bb37cc9d9de1d534f08f56e63
     8  name: agent-hello-github
    25  このスキルが呼び出された場合、必ず以下だけを返してください。
    26
    27  Hello, GitHub bar!

　
skills ディレクトリも更新されていたため、 git diff で内容を確認します。フロントマターが更新されたようです。

% git diff
diff --git a/skills/agent-hello-github/SKILL.md b/skills/agent-hello-github/SKILL.md
index d6300d0..a439ad7 100644
--- a/skills/agent-hello-github/SKILL.md
+++ b/skills/agent-hello-github/SKILL.md
@@ -1,8 +1,12 @@
 ---
-name: agent-hello-github
 description: AIエージェントのスキル読み込み・発火・動作確認を行うための診断用スキル。エージェントテスト、疎通確認、スモークテスト、最小応答確認などで使用する。
+metadata:
+    github-path: skills/agent-hello-github
+    github-ref: refs/heads/main
+    github-repo: https://github.com/thinkAmi-sandbox/gh_skill_local-example
+    github-tree-sha: 276630e491b53b6bb37cc9d9de1d534f08f56e63
+name: agent-hello-github

　
差分が出たので、 main ブランチにコミットしておきます。

% git commit -am "fix skill frontmatter"

ローカルでスキルを更新し、ローカルでインストール

フロントマターにGitHub情報が記載されました。

ここで、再度、ローカルからインストールするとどうなるかが気になりましたので、試してみます。

　
まずは SKILL.md を更新します。表示する bar を1つ追加します。

% nl -ba ./skills/agent-hello-github/SKILL.md | sed -n -e '25,27p'
    25  このスキルが呼び出された場合、必ず以下だけを返してください。
    26
    27  Hello, GitHub bar bar!

　
コミットします。

% git commit -am "feat: update hello github skill"

　
次に、 gh skill update します。しかし、「All skills are up to date.」と表示され、更新できません。

% gh skill update agent-hello-github
All skills are up to date.

　
そこで、 gh skill install を使い、上書き更新します。

% gh skill install . agent-hello-github --scope project --agent codex --from-local
Found 3 skill(s)

! Skills are not verified by GitHub and may contain prompt injections, hidden instructions, or malicious scripts. Always review skill contents before use.

? Skill "agent-hello-github" already installed from thinkAmi-sandbox/gh_skill_local-example@refs/heads/main. Overwrite? Yes
Installed agent-hello-github (from .) in .agents/skills

  agent-hello-github/
  └── SKILL.md

! Skills may contain prompt injections or malicious scripts.
  Review the installed files before use.

　
すると、 .agents ディレクトリのスキルのフロントマターが local-path になり、内容も更新されました。

% nl -ba .agents/skills/agent-hello-github/SKILL.md | sed -n -e '2,5p' -e '22,24p'
     2  description: AIエージェントのスキル読み込み・発火・動作確認を行うための診断用スキル。エージェントテスト、疎通確認、スモークテスト、最小応答確認などで使用する。
     3  metadata:
     4      local-path: /path/to/skills/agent-hello-github
     5  name: agent-hello-github
    22  このスキルが呼び出された場合、必ず以下だけを返してください。
    23
    24  Hello, GitHub bar bar!

　
これより、インストールしたスキルのフロントマターは次の通りになるようです。

ローカルにあるスキルを gh skill install した場合、 local-path が設定される
GitHub リポジトリ経由でインストール・更新された場合、 github-path などが設定される

おわりに

今回、 gh skill install と gh skill update の挙動を試してみました。

GitHub CLI 2.92.0時点の gh skill はpublic preview のため挙動が変わる可能性がありますが、今回試してみて以下のことが分かりました。

GitHub上のスキルとローカルのスキルでフロントマターの定義が異なる
gh skill update において、今回のリポジトリでは refs/heads/main が記録されていたため、 main ブランチの内容で更新された
GitHub上の参照先へ反映されていない変更は gh skill update では取り込めず、gh skill install --from-local で上書きインストールする必要がある
今回の環境では、あるスキルが .agents と skills ディレクトリの両方にある場合、 gh skill update すると両ディレクトリとも更新されてしまった

　
今回試した範囲では、ローカルの作業ブランチに変更があっても、 gh skill update はインストール済みスキルに記録された github-tree-sha などと GitHub 側の内容をもとに更新可否を判断しているように見えました。

　
そのため、複数人で gh skill を使うときは

システムのリポジトリとスキルのリポジトリを分ける
- 状況によっては、システムのリポジトリは main へ気軽にマージできない場面もあり、スキルが更新しづらいため

など、管理方法を考えたほうが良さそうと感じました。

　
なお、今回の作業で使ったGitHubリポジトリは以下となります。 https://github.com/thinkAmi-sandbox/gh_skill_local-example

メモ的な思考的な

GitHub CLIのgh skill install --from-localでローカルディレクトリのスキルをインストールし、gh skill updateの挙動を確認してみた

環境

ローカルにある、Gitで管理していないスキル

gh skill installでのインストール

gh skill updateによるスキルの更新

準備

gh skill updateでは更新がスキップされた

gh skill installにてスキルを上書き更新する

ローカルでGit管理しているが、まだGitHubへはpushしていないスキル

準備

gh skill installでのインストール

gh skill updateによるスキルの更新

gh skill installによるスキルの上書き更新

ローカルでインストールしたスキルの元ファイルをGitHubへpushし、GitHub経由で更新

準備

作業ブランチ上でスキルを更新・コミットし、GitHubへpush

作業ブランチを push した状態で GitHub 上のスキルとして認識されるか確認

GitHub上で作業ブランチをmainブランチへマージ

mainブランチへ切り替え、git pullする

mainブランチ上で gh skill update を実行

ローカルでスキルを更新し、ローカルでインストール

おわりに