SONUB の Agent Skills — コマンド 1 行でインストール

基礎 — スキルとは何か、どうインストールするか

がはじめてなら、ここから始めましょう。スキルとは何か、どう動くのかを学び、コマンド 1 行でインストールして使ってみます。終わったら、上の [中級] タブで自分のスキルを作りましょう。

エージェントスキルについて学ぶ

は、SKILL.mdファイルが入ったフォルダで、エージェントにある種類の作業のやり方を教えます。手順、ルール、確認方法が入っていて、必要ならスクリプトや参考ファイルも入れられます。Claude Code、Codexなどのエージェントは、公開されているAgent Skillsの形式に対応しています。

SKILL.mdのいちばん上には名前と説明があります。エージェントは最初はこれだけを読み、依頼が説明に合ったときに全部の指示を読み込みます。だから、スキルがたくさんあっても会話がいっぱいになりません。

やさしく理解しよう

こんなふうに考えてみよう: スキルは、棚にならんだ説明書のバインダーのようなものです。エージェントは、まず表紙だけを読みます。それぞれのバインダーの名前と一行の説明です。あなたのお願いが表紙に合うと、そのバインダーを取り出して、中の手順どおりに進めます。だから、スキルがたくさんあっても会話がごちゃごちゃしません。
例: 「roll-dice」スキルの例です。SKILL.md が入ったフォルダーで、表紙には「ユーザーが乱数をたのんだらサイコロをふる」と書いてあり、中には手順と小さなスクリプトがあります。「サイコロを二つふって」とたのむと、エージェントはそのバインダーを開きます。
よくある間違い: 「便利なお手伝い」のような、あいまいな説明。エージェントは表紙だけで決めるので、そのスキルをいつ使うべきかをはっきり書きましょう。

カラフルなバインダーがならんだ棚があります。ひとつが開いていて、アイコンと数行が書かれた表紙、点線の手順が書かれたページ、チェックリスト、クリップでとめた小さな道具箱が見えます。ロボットが表紙を読み、ふきだしの中のサイコロのアイコンに合うバインダーを取り出しています。 — エージェントは表紙(名前と説明)だけを読み、お願いに合うバインダーをひとつだけ開きます。

エージェントスキルとは?

エージェントスキル(Agent Skills)は、AIエージェントに新しい能力と専門知識を加える、軽くてオープンな形式です。1つのスキルは、SKILL.mdファイルが入った1つのフォルダです。SKILL.mdには名前(name)と説明(description)、そしてある種類の作業のやり方をエージェントに教える指示が入っています。フォルダには、スクリプト、参考文書、テンプレートなどのファイルも一緒に入れられます。

エージェントはどんどん賢くなっていますが、実際の仕事を安心して任せるには、自分の会社・チーム・自分自身の仕事のやり方を知る必要があります。スキルはそのやり方を1つのフォルダにまとめ、エージェントが必要なときだけ読み込めるようにします。専門知識はくり返し使えるものになり、いくつもの手順がある作業は毎回同じ手順になります。

この形式はAnthropicが最初に作り、オープンな標準として公開しました。今はだれでも参加して、一緒に育てています(agentskills.io)。

役に立つところ — 手順・レビュー基準・文書フォーマットなど、チームが繰り返す仕事です。人が変わっても、仕事のやり方が残ります。

一度学べば、たくさんのAIツールで

エージェントスキルは1つの会社の機能ではなく、公開された標準です。だからスキルの作り方を一度学べば、どこでも使えます。同じSKILL.mdフォルダが、Claude CodeやCodexだけでなく、この形式に対応するたくさんのAIツールでそのまま動きます。

インストールもどこでも同じです。ツールがスキルを探すフォルダに、スキルのフォルダを入れるだけです。ツールによってちがうのは、そのフォルダの場所だけです(下の枠)。

Claude Code
Claude
ChatGPT & Codex
Gemini CLI
GitHub Copilot
VS Code
Cursor
OpenCode
Goose
Kiro
Junie
Roo Code
Amp
OpenHands
Factory
Laravel Boost

agentskills.ioで紹介されているツールの一部です(2026-10-16確認)。リストはどんどん増えています。

# where each tool looks for skills      all projects        this project
Claude Code                             ~/.claude/skills    .claude/skills
Codex · Gemini CLI · Copilot CLI        ~/.agents/skills    .agents/skills
VS Code (GitHub Copilot)                                    .agents/skills
# put the whole skill folder there:  .agents/skills/roll-dice/SKILL.md

しくみ: 必要な分だけ読む3つの段階

エージェントは、スキルを段階的な開示(progressive disclosure)という方法で読みます。最初は少しだけ読み、作業に必要になったときにもっと読みます。

見つける(Discovery): 起動したとき、すべてのスキルの名前と説明だけを読みます。1つのスキルで約100トークンなので、たくさんインストールしても軽いままです。
使い始める(Activation): 依頼があるスキルの説明に合うと、そのスキルのSKILL.mdの本文を全部読みます。本文は5,000トークン、500行より短くするのがおすすめです。
実行する(Execution): 指示にしたがって作業し、必要なときだけscripts/のコードを実行したり、references/の文書を読んだりします。

フォルダの構成とSKILL.mdのルール

スキルに必ず必要なファイルはSKILL.mdだけです。いちばん上に2つの---の行ではさんだYAMLのヘッダーがあり、その下にMarkdownで指示を書きます。

name(必須): 64文字以内で、英小文字・数字・ハイフン(-)だけを使います。ハイフンで始めたり終えたりしてはいけません。ハイフンを2つ続けることもできません。フォルダ名と同じにします。
description(必須): 1,024文字以内。何をするか、いつ使うかを、人が実際に使う言葉で書きます。エージェントはこれを読んで、スキルを使うかどうかを決めます。
license・compatibility・metadata・allowed-tools(任意): ライセンス、必要な環境(500文字以内)、作者やバージョンなどの追加情報、前もって許可したツール(実験的な機能)です。ほとんどのスキルには必要ありません。
scripts/・references/・assets/(任意): 実行するコード、必要なときに読む文書、テンプレート・画像・データなどの素材です。ファイルはスキルのフォルダを基準にした相対パスで指し、SKILL.mdからは1段階の深さまでだけつなぎます。

my-skill/            # folder name = the skill's name
├── SKILL.md         # required: name + description + instructions
├── scripts/         # optional: code the agent can run
├── references/      # optional: documents read only when needed
└── assets/          # optional: templates, images, data

作ってみよう: ファイル1つで5分

いちばん簡単なスキルは、SKILL.mdファイル1つだけです。agentskills.ioのクイックスタート(Quickstart)にある、サイコロを振るスキルを作ってみましょう。

フォルダを作る: プロジェクトに .agents/skills/roll-dice/ フォルダを作ります(Claude Codeなら .claude/skills/roll-dice/)。フォルダ名がそのままスキル名になります。
SKILL.mdを書く: 下の枠のように name と description を書き、本文にやることを数行で書きます。
確認する: エージェントを開き直して /skills と入力し、リストに roll-dice があるか見ます。
試す: 「d20を振って」と頼んでスキルが使われるか見て、関係のない質問では使われないことも確かめます。うまく使われないときは、description を直しましょう。

---
name: roll-dice
description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.), roll dice, or generate a random dice roll.
---

To roll a die, use the following command that generates a random number from 1
to the given number of sides:

```bash
echo $((RANDOM % <sides> + 1))
```

Replace `<sides>` with the number of sides on the die (e.g., 6 for a standard
die, 20 for a d20).

よいスキルを作るコツ

いちばん大切なのは description です。何をするか、いつ使うか、何には使わないかを書きます。「PDFを手伝う」のようにあいまいだと、ほとんど使われません。
1つのスキルには1種類の作業だけを入れます。本文は、短い手順、入力と出力の例、よくある例外で作ります。
長い説明は references/ に、くり返すコマンドや計算は scripts/ に移します。スクリプトには何が必要かを書き、わかりやすいエラーメッセージを出すようにします。
skills-ref validate ./my-skill でヘッダーのルールを確認し、git でスキルを管理して、チームと共有しましょう。
ほかの人が作ったスキルはスクリプトを実行できるので、インストールする前にかならず中身を読みましょう。
使う前に — 他の人が作ったスキルは、指示とスクリプトを先に読みます。元に戻せる小さな作業で試しましょう。Agent Skills のサイトは形式を決めているだけで、スキルが安全だとは保証しません。

もう少し詳しく

スキルがいつ使われるかは説明で決まるので、人が実際に使う言葉で書き、何には使わないかもはっきり書きましょう。指示は短く具体的にし、長い詳細は別の参考ファイルに移し、使うべき依頼と使うべきでない依頼でスキルをテストしましょう。スキルはスクリプトを実行できるので、信頼できる提供元のスキルだけをインストールし、先に中身を読みましょう。SONUB自体も複数のスキルを使って作られています。その1つは、このサイトで目にする用語の初心者向けポップアップを書いています。

コマンド 1 行でインストール

プロジェクトのフォルダでターミナルを開いて実行してください。sonub.com からスキルの一覧を読み込み、どのスキルをどのエージェントに入れるかを聞いてから、エージェントごとにスキルを探すフォルダへコピーします。

npx skills add https://sonub.com

Node.js 18 以上が必要です（npx も一緒に入っています）。インストールしたら、新しいスキルを読み込むようにエージェントの新しいセッションを始めてください。

コマンドを知らなくても — AI に「インストールして」と頼むだけ

スキルをインストールするときは、AI に入れたいスキルをインストールしてと頼めば大丈夫です。AI は賢いので、「https://sonub.com にある gp スキルをインストールして」のように、どこにあるスキルかを伝えればインストールしてくれます。インストールのコマンドを知らなくても、AI がインストールして使ってくれます。下の文をコピーしてエージェントに送ってみましょう。

SONUB のスキルをインストールして：npx skills add https://sonub.com -y を実行して、どのスキルがインストールされたかと、使い始めるには何と言えばよいかを教えて。

ただし、本当に何も知らないまま AI に任せるだけだと、結局は AI が仕事をしたのであって、あなたが仕事をしたことにはなりません。

だからこそ、まず AI について知っておくことが大切です。そうすれば AI にもっと上手に仕事を頼めますし、AI が間違えたときも、AI がした作業を分析して何が間違っていたのかを見つけ、もう一度頼み直せます。

よく使うオプション

このコンピューターのすべてのプロジェクトに（付けなければ今のプロジェクトだけ）: npx skills add https://sonub.com -g
スキルを 1 つだけ: npx skills add https://sonub.com -s gp
エージェント 1 つだけに: npx skills add https://sonub.com -a claude-code
スキルの一覧を見るだけで、インストールしない: npx skills add https://sonub.com -l
何も聞かずに、すべてのスキルをこのコンピューターで見つかったエージェントに: npx skills add https://sonub.com -y

アップデートと削除

ここからインストールしたすべてのスキルを最新にする: npx skills update
スキルを削除する: npx skills remove gp

スキル

どのスキルも、SKILL.md（エージェントが読む指示書）と小さなツールが入った標準のフォルダです。登録は不要で、MIT ライセンスです。

gp

すべての作業を GitHub Project ボードで

ふだんの言葉で話しかけるだけで、エージェントが gh CLI で GitHub Project ボードを管理し、結果を読み直して確認します。

こう話しかけてみて

「自分の担当は？」
「#12 を Review に移して」
「TODO に『ドキュメントを更新』を追加して」
「先頭に Urgent 列を追加して」

やってみよう: gp スキルで仕事を管理する

gp は SONUB が作ったで、自分の仕事をすべて Project のボードで管理します。次のようなことを普段の言葉で頼むと、が GitHub (gh)で処理し、結果を読み直して確認します。

Issue の作成・編集・クローズ、画像の添付
TODO チェックリスト
かんばんの列の追加・名前の変更
担当者の割り当て

スキルのフォルダーには、上で説明した部品がそのまま入っています。SKILL.md、実際に作業するスクリプト(scripts/gp.py)、必要なときだけ読む参考ファイルです。

準備: github.com/signup で無料の GitHub アカウントを作り、gh をインストールします。ログインは gh auth login でエージェントが手伝います。
インストール: 下の 1 行をターミナルに入力します（Node.js が必要です）。パソコンのエージェント（Claude Code・Codex・Gemini CLI など）に gp が入ります。
最初の 1 回: 「gp を設定して」と言います。エージェントが gp の doctor コマンドで確認し、自分のボードを 1 つ選ぶか新しく作ります。
普段の言葉で頼みます: 「Issue を作って: ログインボタンが反応しない、このスクリーンショットを添付して」「Done に移して」「Review 列を作って」「自分の仕事を見せて」。

# 1) install the gp skill — Claude Code, Codex, Gemini CLI, Copilot CLI ...
npx skills add https://sonub.com -s gp -g
#   -g: for every project (leave it out for this project only)

# 2) once: log in to GitHub with the board permissions
gh auth login
gh auth refresh -s project,repo

# 3) then just ask the agent:
# "Set up gp and show my GitHub projects."
# "Make an issue: the login button does nothing. Attach shot.png. TODO: reproduce, fix, test."
# "Move it to In Progress."   "Add a Review column."   "Done!"   "What's on my plate?"

無料の GitHub アカウント、gh CLI、Python 3.8 以上が必要です。

このスキルをインストール

npx skills add https://sonub.com -s gp

SKILL.md を読む

claude-skill

Claude Code を学んで、もっと上手に使う

Claude Code はほぼ毎日新しいバージョンが出ます。このスキルは順を追って教え、最新の公式ドキュメントをもとに答え、設定をチェックし、新機能をもれなくまとめます。

こう話しかけてみて

「次のレッスン」
「編集のたびに hook で prettier を実行するには？」
「設定をチェックして」
「クイズを出して」

Python 3.8 以上とインターネット接続が必要です（公式ドキュメントを読み込みます）。

このスキルをインストール

npx skills add https://sonub.com -s claude-skill

SKILL.md を読む

難しい言葉を、読み手が出会ったその場で説明する

プロジェクトのどのページやドキュメントでも、専門用語にマウスを乗せる（スマートフォンではタップする）と、小さなカードが説明してくれます。意味、やさしい言葉での説明、例、ソースコード、「詳しく見る」リンクが表示されます。

用語集の JSON 1 つが、公開するすべての言語のすべての説明の元になります
popup.js と popup.css を置くだけ。フレームワークもビルド手順も不要です
通常のテキスト中の用語は自動で見つけ、フレーズ・「?」ボタン・リンクのプレビューは手動で付けます
キーボード、スマートフォン（ボトムシート）、右から左へ書く言語、ダークモードに対応
ドキュメント内の、まだ説明のない専門用語を見つける監査機能
GitHub の README 向け：GLOSSARY.md と、マウスを乗せると意味が表示されるリンク

こう話しかけてみて

「はじめにページに用語ポップアップを付けて」
「token、sampling、temperature をマウスを乗せると説明されるようにして」
「README を初心者にもやさしくして」
「ドキュメントの中で、まだ説明が必要な言葉はどれ？」

ツールには Python 3.8 以上が必要です。ポップアップはどの最新ブラウザでも動きます。

このスキルをインストール

npx skills add https://sonub.com -s popup

popup の使い方 — 詳しいガイド SKILL.md を読む

よくある質問

Agent Skill とは？

AI エージェントに、いつ・どうやって作業するかを伝える SKILL.md ファイルと、必要なスクリプトやメモをまとめたフォルダです。オープンな標準（agentskills.io）なので、同じフォルダが多くのエージェントで動きます。

すべてのプロジェクト？それともこのプロジェクトだけ？

-g を付けなければ、今いるプロジェクトの中（たとえば .claude/skills/ や .agents/skills/）にインストールされます。コミットすればチームのみんなも使えます。-g を付けると、ホームフォルダに一度インストールするだけで、すべてのプロジェクトで使えます。

どのエージェントで使えますか？

Claude Code、Codex、Gemini CLI、GitHub Copilot CLI、Cursor など、skills ツールが知っているエージェントで使えます。どのエージェントに入れるかを聞いてくれます。-a で 1 つを指定することもできます。

無料ですか？データはどこに送られますか？

無料で、MIT ライセンスです。スキルはあなたのコンピューター上で、あなた自身のツールを使って動きます。gp はあなたの gh ログインで GitHub とだけ通信し、claude-skill は公開されている Claude Code のドキュメントを読み、popup はあなたのファイルだけを扱います。sonub.com はスキルのファイルを配るだけです。

インストールしたのに表示されません。どうすれば？

エージェントの新しいセッションを始めてください。エージェントは起動するときにスキルのフォルダを読み込みます。Claude Code では、/gp のようにスラッシュに続けてスキル名を入力することもできます。

授業で教える — AI 講座の Agent Skills の章

中級 — 自分のスキルを作る

何度もくり返すお願いをにします。フォルダーを作り、が見つけられる説明を書き、短い手順を書いてから、呼び出して確認し、自分だけで使うかチーム全員で使うか、置き場所を決めます。

はじめてのスキル — くり返すお願いをスキルに

はじめてのスキルに向いているのは、にもう 3 回以上説明したことです。たとえば、メッセージの書き方、テストの手順、報告書の形です。その説明を SKILL.md に一度書いておけば、エージェントが毎回見つけて従います。

いつも説明している作業を 1 つ選び、小文字・数字・ハイフンで短い名前をつけます（commit-message）。
エージェントのスキルフォルダーに、その名前でフォルダーを作ります。npx skills init <name> でフォルダーと SKILL.md のひな形ができます。
いちばん上に name（フォルダー名と同じ）と description を書き、その下に手順を書きます。
新しいセッションを始め、その作業をふだんの言葉でお願いします。エージェントがスキルを使えば成功です。

Terminal

# in your project folder
mkdir -p .agents/skills && cd .agents/skills
npx skills init commit-message      # makes commit-message/SKILL.md

# Codex · Gemini CLI · Copilot CLI read   .agents/skills/commit-message/SKILL.md
# Claude Code reads                       .claude/skills/commit-message/SKILL.md

エージェントに「今やったことをスキルにして」と頼んでもかまいません。Claude Code と Codex は形式を知っています（Codex には $skill-creator が組み込まれています）。

description — エージェントが持つただ 1 つの手がかり

最初、エージェントはすべてのスキルの名前と説明（description）だけを読みます。その数行から、今のお願いに合うスキルを選びます。説明があいまいだと、スキルはまったく使われないか、まちがったときに使われます。

何をするか、いつ使うかを、両方とも 1〜2 文で書きます。
"I can help you …" ではなく、3 人称（"Writes commit messages …"）で書きます。
人が実際に入力する言葉を入れます："commit message"、"commit this"、"staged changes"。
ルール：description は 1,024 文字まで。name は小文字・数字・ハイフンで 64 文字までで、フォルダー名と同じにします。

SKILL.md

# ✗ too vague — the agent cannot tell when to use it
description: Helps with commits.

# ✓ what it does + when to use it + the words people really say
description: Writes a git commit message from the staged changes in the Conventional Commits style. Use when the user asks for a commit message, says "commit this", or wants to describe staged changes.

Claude Code はスキル一覧で説明を 1,536 文字までしか表示しないので、いちばん大事な使い道を先頭に書きましょう。

本文の指示 — 短く、順番に、例をつけて

frontmatter の下は、エージェントがスキルを使うときに読む指示です。エージェントはもう賢いので、知らないことだけを書きます：あなたのルール、手順の順番、形式です。

エージェントがすでに知っていること（git とは何か、Markdown の書き方）は省きます。
順番が大事なら番号をつけ、うまくいかないときにどうするかも書きます（「ステージされたものがなければ、そう伝えて止まる」）。
ほしい結果を 1〜2 個の例で見せます — 例は説明よりよく伝わります。
選択肢を並べず、決まったやり方を 1 つ示します（「pdfplumber を使う。スキャンした PDF だけ OCR を使う」）。
SKILL.md は 500 行未満にします。長くなったらファイルに分けます（[上級] タブ）。

.agents/skills/commit-message/SKILL.md

---
name: commit-message
description: Writes a git commit message from the staged changes in the Conventional Commits style. Use when the user asks for a commit message or says "commit this".
---

1. Run `git diff --staged`. If nothing is staged, say so and stop.
2. Pick one type: feat, fix, docs, refactor, test or chore.
3. Write a subject of 50 characters or less, then a blank line,
   then why the change was made in one or two short lines.

Example:
fix(cart): keep the coupon after a page reload

The coupon code was stored only in memory.

スキルの呼び出しと確認

スキルの使われ方は 2 つあります。お願いが説明に合うとエージェントが自分で選ぶか、あなたが名前で呼び出すかです。

自動：ふだんの言葉でお願いするだけです（「コミットメッセージを書いて」）。エージェントが説明を読んでスキルを読み込みます。
Claude Code：/skills で一覧を見て、/<skill-name> で呼び出します。名前のあとの言葉は $ARGUMENTS に入ります。
Codex：/skills で一覧を見て、メッセージに $<skill-name> と書くと呼び出せます。
Claude Code は SKILL.md の変更をすぐ反映します。スキルフォルダーを新しく作ったときは /reload-skills を実行します。ほかのツールでは新しいセッションを始めます。

Claude Code · Codex

# Claude Code
/skills                 # list the skills it found
/commit-message         # call one yourself
/fix-issue 123          # "123" goes into $ARGUMENTS in SKILL.md

# Codex
/skills                 # list and pick
$commit-message         # mention one in your message

使われるべきときにスキルが使われないなら、まず description を直しましょう — ほとんどの場合、それが原因です。

同じスキルを、ホームフォルダー（自分のすべてのプロジェクト用）にも、プロジェクト（そこで作業する全員用）にも置けます。

個人のスキル：Claude Code は ~/.claude/skills/、Codex・Gemini CLI・Copilot CLI は ~/.agents/skills/。
プロジェクトのスキル：プロジェクトの .claude/skills/ か .agents/skills/。コミットすれば、チーム全員が同じスキルを使えます。
同じ名前のスキルが 2 つあると、Claude Code は個人のスキルをプロジェクトのスキルより優先します。
スキルにパスワードや API キーを入れてはいけません — スキルのファイルは読まれ、よく共有されます。

Where

# only me, every project
~/.claude/skills/commit-message/      # Claude Code
~/.agents/skills/commit-message/      # Codex · Gemini CLI · Copilot CLI

# this project — commit it and the whole team gets it
.claude/skills/commit-message/
.agents/skills/commit-message/

git add .agents/skills/commit-message
git commit -m "Add the commit-message skill"

中級の練習 — 自分のプロジェクトで 1 つ作る

AI に 3 回以上したお願いを 1 つ書き出します。
npx skills init でそのスキルのフォルダーを作り、name と description を書きます。
手順を 5 行以内で書き、結果の例を 1 つ入れます。
新しいセッションでふだんの言葉でお願いし、スキルが使われるか確認します。次に名前で呼び出してみます。
関係のないことをお願いして、スキルが使われないことも確認します。

5 つすべてできたら、[上級] タブに進みましょう。

公式ドキュメント

2026-10-18 に公式ドキュメントで確認しました。これらのツールはよく変わるので、コマンドが動かないときは公式ドキュメントを見てください。

上級 — 大きなスキル：ファイル・スクリプト・オプション・テスト・安全

SKILL.md 1 つでは足りないとき：必要なときだけ読むファイルに分け、決まった作業はスクリプトに任せ、frontmatter のオプションを使い、信頼する前にテストし、ほかの人のはインストール前に確認します。

ファイルに分ける — 必要なものだけ読ませる

はスキルを 3 段階で読みます。最初は名前と説明、スキルを使うときに SKILL.md、ほかのファイルは必要なときだけです。だから大きな資料は別のファイルに置き、SKILL.md はどの質問でどのファイルを読むかを示す地図にします。

SKILL.md には全体の説明と「これのときは、あのファイルを読む」を書きます。
ファイルへのリンクは SKILL.md から 1 段階だけにします。ファイル → ファイル → ファイルのようにつながると、一部しか読まれないことがよくあります。
100 行を超える参考ファイルは、いちばん上に目次を置きます。
ファイル名は中身がわかる名前にし（doc2.md ではなく finance.md）、パスはいつも / で書きます。

sql-report/

sql-report/
├── SKILL.md              ← the map: what to read for which question
├── references/
│   ├── finance.md        ← read only for revenue questions
│   └── sales.md          ← read only for sales questions
└── scripts/
    └── check_query.py    ← run it, do not read it

SKILL.md

## Which file to read
- Revenue, billing → read [references/finance.md](references/finance.md)
- Deals, pipeline → read [references/sales.md](references/sales.md)

スクリプト — 毎回同じでなければならない作業はコードに

用意したスクリプトは、エージェントがその場で書くより信頼できます。実行すると、コードではなく出力だけがコンテキストに入ります。チェックや変換など正確さが必要な作業は scripts/ に置きます。

実行するのか（"Run scripts/check_query.py"）、読むのか（「ルールは scripts/check_query.py を見る」）をはっきり書きます。
エラーはスクリプトの中で処理し、何がまちがっていて、どうすればよいかを伝えるメッセージを出します。
必要なパッケージとバージョンを書き、本当に必要なものは compatibility にも書きます。
チェック → 修正 → もう一度チェック、というループを作り、チェックに通ってから次へ進みます。
決めた値には理由をコメントで書きます（なぜタイムアウトが 30 秒なのか？）。

SKILL.md

## Check the query before you run it

Run:
    python3 scripts/check_query.py query.sql

It prints OK, or one problem per line.
If it is not OK, fix the query and run the check again.
Run the query only after you see OK.

どの言語を実行できるかはエージェントによってちがいます。よく使われるのは Python・Bash・JavaScript です。

frontmatter のオプション — 標準と、ツールごとのおまけ

name と description のほかに、標準にはいくつかの任意フィールドがあり、ツールごとに独自のフィールドも追加されます。ツールは知らないフィールドを無視するので、まず標準フィールドだけで動くようにしましょう。

標準：license、compatibility（必要なプログラムやネットワーク、500 文字まで）、metadata（作者など）、allowed-tools（事前に許可したツール — 実験的）。
Claude Code の disable-model-invocation: true — あなただけが呼び出せます。デプロイやメッセージ送信など、副作用のある作業に使います。
Claude Code の user-invocable: false — AI だけが使い、/ メニューには表示されません。context: fork はスキルをサブエージェントで実行します。
Claude Code の !`command` — スキルが読まれる前にコマンドを実行し、その出力に置きかえます（例：!`git diff HEAD`）。
Codex：agents/openai.yaml の policy → allow_implicit_invocation: false — $<skill-name> で呼んだときだけスキルが使われます。

.claude/skills/deploy/SKILL.md

---
name: deploy
description: Deploys the app to staging or production. Use when the user says deploy, release or ship.
license: MIT
compatibility: Requires git, docker and network access
metadata:
  author: my-team
allowed-tools: Bash(git status) Bash(./scripts/deploy.sh *)
# Claude Code only — other tools ignore these
disable-model-invocation: true
argument-hint: "[staging|production]"
---

Current branch: !`git branch --show-current`

Deploy to $ARGUMENTS with `./scripts/deploy.sh $ARGUMENTS`.

allowed-tools には、スキルに本当に必要なコマンドだけを入れましょう。権限が広いほど、ミスの代償が大きくなります。

テスト — たくさん書く前に、まずテストを書く

スキルがうまく動くかは、試してみないとわかりません。まずスキルなしでエージェントが何をまちがえるかを見て、それを直すのに必要な分だけ書きます。

スキルなしでエージェントにその作業をさせ、まちがいや抜けを書き出します。
その抜けを確かめるテスト用のお願いを 3 つ以上作ります — スキルが使われてはいけないお願いも 1 つ入れます。
抜けを埋めるのに必要な分だけ指示を書きます。
新しいセッションで、同じお願いをスキルありとスキルなしで試し、くらべます。
使うモデルすべてでテストします — 小さなモデルには、もっとくわしい説明が必要なことがあります。

Terminal

# checks the frontmatter and the naming rules
skills-ref validate ./commit-message

evals.json (your own format)

[
  {"query": "write a commit message for what I staged", "use_skill": true},
  {"query": "commit this, it fixes the login bug",      "use_skill": true},
  {"query": "explain what git rebase does",             "use_skill": false}
]

skills-ref は agentskills リポジトリにある参考ツール（デモ用）です — クローンして pip install -e . でインストールします。Claude Code では /skill-doctor が、スキルごとのコンテキストの消費量と使用回数を表示します。

安全 — ほかの人のスキルはコードのように読む

スキルはエージェントが従う指示で、そのスクリプトはあなたのコンピューターで実行されます。悪いスキルはエージェントに悪い指示を従わせるので、インストール前に確認しましょう。

信頼できる場所からだけインストールします。-l をつけると、インストールせずに一覧だけ見られます。
インストールする前に、SKILL.md と scripts/ のすべてのファイルを読みます。
ファイルやキーをほかの場所へ送るコマンドや、何かを削除するコマンドがないか確認します。
スキルにパスワードやキーを入れず、環境変数から読むようにします。
Claude Code：Skill(deploy *) のような権限ルールでスキルをブロックし、disableSkillShellExecution 設定で !`command` をオフにします。

Terminal

# see what is inside before you install
npx skills add my-name/my-skills -l

# read the instructions and every script
cat .agents/skills/<name>/SKILL.md
ls .agents/skills/<name>/scripts/

自分のスキルも同じです。コミットや共有の前に、変更をもう一度読みましょう。

上級の練習 — 自分のスキルを育てる

中級で作ったスキルの長い部分を references/ に移し、SKILL.md からリンクします。
scripts/ にチェックを 1 つ書き、SKILL.md に「チェック → 修正 → もう一度チェック」の手順を加えます。
スキルのフォルダーに skills-ref validate を実行し、指摘されたところを直します。
テスト用のお願いを 3 つ（スキルが使われてはいけないもの 1 つを含む）作り、スキルありとなしでくらべます。
ほかの人が作ったスキルを 1 つ、インストールする前に最初から最後まで読みます。

5 つすべてやったら、[マスター] タブに進みましょう。

公式ドキュメント

2026-10-18 に公式ドキュメントで確認しました。これらのツールはよく変わるので、コマンドが動かないときは公式ドキュメントを見てください。

マスター — 公開・ツールをまたぐ・設計・スキルの手入れ

だれでもコマンド 1 行でインストールできるようにを公開し、1 つのスキルをすべてので動かし、スキルが正しい道具なのはいつかを決め、使いながらスキルをよい状態に保ちます。

スキルを公開する — GitHub リポジトリ 1 つで

スキルを公開のに置けば、だれでも npx skills add <owner>/<repo> でインストールできます。1 つのリポジトリに、たくさんのスキルを置けます。

スキルごとに skills/ の下に専用のフォルダーを作ります。インストーラーが見つけてくれます。
LICENSE と、各スキルが何をするかとインストールコマンドを書いた README を置きます。
使う人は -s でスキルを 1 つだけ選び、-g ですべてのプロジェクトにインストールできます。
スキルを直して push すれば、使う人は npx skills update で受け取れます。

my-skills/

my-skills/                     # a public GitHub repository
├── README.md                  ← what each skill does + the install command
├── LICENSE
└── skills/
    ├── commit-message/SKILL.md
    └── sql-report/SKILL.md

# anyone can install it
npx skills add my-name/my-skills
npx skills add my-name/my-skills -s commit-message -g
npx skills update              # gets your new commits

自分のウェブサイトから公開する — SONUB のように

自分のウェブサイトからスキルを公開することもできます。SONUB はそうしています：npx skills add ://sonub.com は /.well-known/agent-skills/index.json の一覧を読み、スキルごとにアーカイブをダウンロードします。

一覧には、スキルごとの名前・説明・アーカイブのアドレスと、そのアーカイブの sha256 digest があります。
digest が変わると、npx skills update がそのスキルをもう一度ダウンロードします — 変わったスキルだけが更新されます。
name や description がルール（フォルダー名と同じ小文字の名前、1,024 文字までの説明）を破っていると、インストーラーはそのスキルを何も言わずに飛ばします。
SONUB はリクエストのたびにスキルフォルダーから一覧とアーカイブを作るので、直したスキルをデプロイすれば、それが新しいバージョンになります。

sonub.com

# the list the installer reads
https://sonub.com/.well-known/agent-skills/index.json

# one archive per skill, with the sha256 digest of its bytes in the list
https://sonub.com/.well-known/agent-skills/gp.tar.gz

npx skills add https://sonub.com

SONUB のスキルとインストールコマンド

1 つのスキルをすべてのツールで

Agent Skills は公開された標準なので、1 つのフォルダーが Claude Code・Codex・Gemini CLI・GitHub Copilot などでそのまま動きます。ちがうのは、ツールごとに読むフォルダーだけです。

標準フィールド（name・description）とふつうの指示だけで動くようにします。ツール専用のオプションはおまけです。
1 つのツールに結びついた言葉（「Bash ツール」）は避け、「ターミナルで実行する」のように書きます。
本物のフォルダーは .agents/skills/ に 1 つ置き、.claude/skills/ にはリンクを張ります。npx skills add がこれをやってくれます（おすすめ）。--copy をつけるとコピーします。
Claude Code では、スキルをサブエージェント・フック・MCP といっしょにプラグインにまとめ、マーケットプレイスで共有することもできます。

Terminal

# one real folder for every tool
.agents/skills/commit-message/

# a link so Claude Code finds the same folder
mkdir -p .claude/skills
ln -s ../../.agents/skills/commit-message .claude/skills/commit-message

スキルで MCP ツールを使うときは、サーバー名をつけた完全な名前（ServerName:tool_name）で書きます。ないと、エージェントがツールを見つけられないことがあります。

Claude Code マスター — プラグイン

設計 — スキルにするとき、ほかのものにするとき

エージェントに教える方法はいくつもあります。スキルが合うところにスキルを使えば、作業はシンプルになります。

すべての会話で守るルール → AGENTS.md（または CLAUDE.md）。
ときどき必要になる手順や知識 → スキル。
大きな作業を任せて、結果だけ受け取る → サブエージェント。
外部のサービスやデータとつなぐ → MCP。そのツールの使い方はスキルで教えられます。
毎回かならず起きなければならないこと（編集のたびのフォーマット） → フック。

1 つのスキルに 1 つの仕事。スキルがやることが多すぎたら分けましょう。

スキルの手入れ — 使いながらよくする

スキルは推測ではなく、動くようすを見ることでよくなります。実際の作業で使い、エージェントが迷うところを直します。

エージェントの使い方を見ます：一度も読まないファイル、何度も読み直すファイル、見落とすルール。
1 つの AI セッションでスキルを直し、新しいセッションでテストします — 新しいセッションが、足りないものを見せてくれます。
日付（「8 月より前は …」）ではなく今のやり方を書き、古いやり方は「古いやり方」の節にまとめます。
だれも使わないスキルは削除します — 説明の 1 つ 1 つが、すべてのセッションでコンテキストを使います。
チームに聞きます：期待どおりに始まったか？指示はわかりやすかったか？何が足りなかったか？

マスターのチェックリスト

description に、何をするか・いつ使うか・人が実際に使う言葉が書いてある
SKILL.md は 500 行未満で、ほかのファイルへのリンクは 1 段階だけ
スクリプトは自分でエラーを処理し、実行するのか読むのかがはっきりしている
テストが 3 つ以上あり、スキルが使われてはいけない場合も含まれている
秘密の値が入っておらず、ほかの人のスキルは読んでからインストールする
使うエージェントとモデルで確認し、インストールコマンドといっしょに公開した

すべてチェックできたら、自分のスキルを 1 つ GitHub に公開して、npx skills add で共有してみましょう。

公式ドキュメント

2026-10-18 に公式ドキュメントで確認しました。これらのツールはよく変わるので、コマンドが動かないときは公式ドキュメントを見てください。

基礎 — スキルとは何か、どうインストールするか

エージェントスキルについて学ぶ

やさしく理解しよう

エージェントスキルとは?

一度学べば、たくさんのAIツールで

しくみ: 必要な分だけ読む3つの段階

フォルダの構成とSKILL.mdのルール

作ってみよう: ファイル1つで5分

よいスキルを作るコツ

コマンド 1 行でインストール

コマンドを知らなくても — AI に「インストールして」と頼むだけ

よく使うオプション

アップデートと削除

スキル

こう話しかけてみて

やってみよう: gp スキルで仕事を管理する

このスキルをインストール

こう話しかけてみて

このスキルをインストール

こう話しかけてみて

このスキルをインストール

よくある質問

中級 — 自分のスキルを作る

はじめてのスキル — くり返すお願いをスキルに

description — エージェントが持つただ 1 つの手がかり

本文の指示 — 短く、順番に、例をつけて

スキルの呼び出しと確認

どこに置くか — 自分だけか、チームでいっしょにか

中級の練習 — 自分のプロジェクトで 1 つ作る

公式ドキュメント

上級 — 大きなスキル：ファイル・スクリプト・オプション・テスト・安全

ファイルに分ける — 必要なものだけ読ませる

スクリプト — 毎回同じでなければならない作業はコードに

frontmatter のオプション — 標準と、ツールごとのおまけ

テスト — たくさん書く前に、まずテストを書く

安全 — ほかの人のスキルはコードのように読む

上級の練習 — 自分のスキルを育てる

公式ドキュメント

マスター — 公開・ツールをまたぐ・設計・スキルの手入れ

スキルを公開する — GitHub リポジトリ 1 つで

自分のウェブサイトから公開する — SONUB のように

1 つのスキルをすべてのツールで

設計 — スキルにするとき、ほかのものにするとき

スキルの手入れ — 使いながらよくする

マスターのチェックリスト

公式ドキュメント

制作

コミュニティ

その他