AI エージェントに新しいスキルを。たった 1 分で。

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

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

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

# 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 文字までで、フォルダー名と同じにします。

# ✗ 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 行未満にします。長くなったらファイルに分けます（[上級] タブ）。

---
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
/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 キーを入れてはいけません — スキルのファイルは読まれ、よく共有されます。

# 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 つ作る

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

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

公式ドキュメント

• Agent Skills — Quickstart
• Agent Skills — Specification
• Claude Code — Skills
• Codex — Skills

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

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

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

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

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

## 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 秒なのか？）。

## 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> で呼んだときだけスキルが使われます。

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

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

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

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

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

[
  {"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` をオフにします。

# 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/

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

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

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

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

公式ドキュメント

• Skill authoring best practices
• Agent Skills — Specification
• skills-ref — GitHub
• Claude Code — Skills

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

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

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

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

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 https://sonub.com は /.well-known/agent-skills/index.json の一覧を読み、スキルごとにアーカイブをダウンロードします。

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

# 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 といっしょにプラグインにまとめ、マーケットプレイスで共有することもできます。

# 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 つの仕事。スキルがやることが多すぎたら分けましょう。

• Claude Code 上級 — スキル・サブエージェント・フック・MCP
• Codex 上級 — 設定・MCP・スキル・フック

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

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

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

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

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

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

公式ドキュメント

• skills CLI (npx skills) — GitHub
• Agent Skills
• Claude Code — Plugins
• Skill authoring best practices

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