4
3

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@aktsmm(やまぱん！)inMicrosoft

Claude Code の Skills 記事を読んで、Gotchas から Agent Skill 設計を見直した話

4
Last updated at Posted at 2026-06-06

こんにちは、Agent Skill を増やすたびに「これは instruction なのか skill なのか？」で立ち止まりがちなアーキテクトのやまぱん！です 😅
補足コメントや質問、いいね、拡散、ぜひお願いします 🥺！
間違っていたら 優しく 教えてください！

この記事は 2026/06/06 時点で確認した内容です。主なきっかけは Anthropic Blog の Lessons from building Claude Code: how we use skills です。

Agent Skills の基本や Tool / Instructions との違いは、以前書いた 🔥 はじめての Agent Skills 🔥 12 選＆リポジトリ一覧！GitHub Copilot でも使える AI の手順書 にまとめています。今回はその続きとして、Skill をどう設計・運用するかに寄せて書きます。

正直に言うと、最近は「これ、モデルが進化したら Skill いらなくなるのでは？」と感じる場面も増えていました。一般的な手順や説明だけを詰めた Skill なら、たぶんそのうちモデル側が普通にできるようになります。

だからこそ今回刺さったのが Gotchas でした。モデルが賢くなっても、私の環境で毎回つまずくこと、特定の repo で失敗しやすい判断、検証で見つかった落とし穴は残ります。Skill に残す価値があるのは、一般論よりもこの「現場のハマりどころ」なんだと思います。

TL;DR

  • Claude Code チームは、社内で数百件の Skills を運用している経験から、Skills を 9 カテゴリに整理していました
  • これは Claude Code だけの話ではなく、AI エージェントに作業手順を渡すための汎用的な考え方です
  • モデルが進化すると不要になる Skill もある。だから一般論より Gotchas（落とし穴） を残す方が長く効くと感じました
  • Skill は 手順・スクリプト・参考資料・検証観点をまとめたフォルダ として扱う考え
  • VS Code の Agent Skills でも、Skill は instructions / scripts / resources を含むタスク特化の再利用単位として説明されています
  • 私の中では、copilot-instructions.md や Agents.md などに常時載せる内容と、必要なときだけ呼ぶ Skill の線引きが前よりはっきりしました
  • 次に Skill を作るなら、まず「検証」「Gotchas（落とし穴・ハマりどころ）」「description」から見直します

Agent Skills を作る・使う・改善する循環

元記事で書かれていること

元記事は、Claude Code チームが社内で数百件の Skills を使ってきた経験をもとに、次の流れで整理しています。

元記事の話題 内容
What are skills? Skill は Markdown だけではなく、instructions / scripts / resources を含むフォルダだと説明
Types of skills Anthropic 社内の Skills を 9 カテゴリに分類
Tips for making skills 自明なことを書かない、Gotchas を育てる、description をモデル向けに書く、などの作り方
Distributing skills repo に入れる方法、plugin / marketplace 的に配布する方法
Composing / Measuring skills Skill 同士の参照、PreToolUse hook による利用状況の測定

この記事では、このうち特に「Skill はフォルダ」「9 カテゴリ」「検証 Skill」「description」「Gotchas」を自分の GitHub Copilot 運用に引き寄せて見ます。

Skill はフォルダ

Anthropic の記事は、Claude Code で Skills をどう使っているかをまとめたものです。

Skills are folders of instructions, scripts, and resources that agents can discover and use to do things more accurately and efficiently.

Skill はフォルダです。SKILL.md に加えて、スクリプト、テンプレート、参考資料を同じ場所に置けます。

この考え方は Claude Code に閉じません。Agent Skills は AI エージェント向けの標準形式で、VS Code の GitHub Copilot でも、Copilot CLI でも、Copilot cloud agent でも使えます。Claude Code の実践記事を読んでいますが、見ているのは「AI エージェントにどう作業手順を渡すか」です。

私はこれまで instructions、prompts、agents、skills を行き来しながら整備してきました。この説明を読んで、自分の置き場所ルールを見直しました。置き場所を間違えると、正しい内容でも常時 context を重くします。必要なときだけ呼べる Skill へ、まだ分けられます。

Claude Code チームの 9 カテゴリ

元記事では、Anthropic 社内の Skills を棚卸しした結果、9 つのカテゴリに分けられると紹介されています。

カテゴリ 何を担う Skill か 私の環境に置き換えるなら
Library and API reference ライブラリ、CLI、SDK の使い方や落とし穴 SDK / CLI / 社内 wrapper の使い方
Product verification UI や CLI の動作確認、状態検証 Playwright、CLI、スクリーンショット確認
Data fetching and analysis データ取得、監視、分析 Azure / GitHub / M365 の調査補助
Business process and team automation 定型業務の自動化 日報、週次まとめ、投稿文生成
Code scaffolding and templates ひな形生成 記事、スライド、設定ファイルのテンプレート
Code quality and review 品質レビュー、スタイル確認 PR レビュー、セキュリティレビュー
CI/CD and deployment CI、デプロイ、リリース GitHub Actions の調査やリリース確認
Runbooks 障害対応や調査手順 ネットワーク、CDP、ローカル環境の復旧手順
Infrastructure operations インフラ運用、削除や保守 Azure 検証環境、クリーンアップ、コスト調査

この表は、そのまま自分の Skill 棚卸しに使えます。

棚卸しするときは、「この Skill は何カテゴリなのか？」と先に聞くことにします。1 つの Skill がレビューもデプロイも調査も記事化も全部やろうとしていたら、たぶん太りすぎです。

Anthropic の記事でも、良い Skill は 1 つのカテゴリにきれいに収まり、複数カテゴリをまたぐものは agent を混乱させやすい、と書かれていました。Copilot 側でも、1 つの Skill に詰めるほど呼び出し判断が曖昧になります。

検証 Skill から作りたい

元記事の中では、Product verification Skills の話が実務に近かったです。

Anthropic は、社内で Claude の出力品質に最も測定可能な効果があったものとして、検証系 Skill を挙げています。エンジニアが 1 週間かけて検証 Skill を良くするだけの意味がある、という強めの表現でした。

検証 Skill で決めるのは、「どう作るか」よりも「どう確かめるか」です。

  • Web UI なら Playwright で画面を操作する
  • CLI なら成功ログだけでなく成果物の存在を確認する
  • PowerPoint なら開いて、はみ出しや URL リンクを確認する
  • 記事なら frontmatter、タグ、出典、公開対象ディレクトリを確認する

このあたりを Skill にしておけば、検証の順番や合格条件を持ち回れます。

検証手順を Skill 側に寄せると、毎回「何を確認するか」を会話で説明し直さずに済みます。

VS Code / GitHub Copilot 側の整理ともつながる

VS Code の公式ドキュメントでも、Agent Skills は次のように説明されています。

Agent Skills are folders of instructions, scripts, and resources that GitHub Copilot can load when relevant to perform specialized tasks.

さらに、Agent Skills と custom instructions の違いも整理されています。

観点 Agent Skills custom instructions
目的 特定タスクの能力や workflow を教える コーディング規約や一般方針を教える
内容 instructions、scripts、examples、resources 主に instructions
読み込み 関連タスクで on-demand 常時、または glob に応じて適用
使い回し VS Code、Copilot CLI、Copilot cloud agent などで持ち回りやすい VS Code / GitHub.com 寄り

copilot-instructions.md や Agents.md、.instructions.md に何でも書く運用は、やっぱり重くなりやすいです。

常時効かせたい短い方針は instructions。タスクとして呼び出したい手順、検証、テンプレート、スクリプトは Skill。この線で分けると扱いやすくなります。

ここが刺さった: Skill は「一般論」より「ハマりどころ」を入れる

元記事の後半には、Skill の作り方に関する Tips も並んでいます。全部をそのまま持ってくるより、自分の運用に効くものだけ拾うなら、この 3 つでした。

  • 自明なことを書かない
  • Gotchas（落とし穴・ハマりどころ）を育てる
  • SKILL.md を入口にして、詳細は references/ や scripts/ に逃がす

特に刺さったのは、自明なことを書かない と Gotchas を育てる です。Skill に何でも説明したくなるけど、AI がすでに知っている一般論を書いても context が増えるだけ。むしろ、過去に自分が詰まった落とし穴を残す方が、次の作業に効きます。

今後 Skill を直すときは、まず「手順を増やす」より 「Gotchas を増やす」 を見ます。ここは今回いちばん持ち帰りたいところです。

自明なことを書かない

元記事では、Claude はすでにコードを読めるし、一般的なコーディングも分かっている、という前提で書かれています。だから Skill に「コードを読んで、テストを書いて、実行する」と書いても、あまり情報は増えません。

Skill に入れるなら、普通の手順よりもローカルな判断です。

  • どのテストを見るか
  • 成功ログだけでは足りない場面はどこか
  • この repo で毎回間違える名前や状態は何か
  • どの確認を飛ばすと手戻りになるか

このあたりは、一般的な AI モデルの知識には入りません。Skill に残す意味があります。

ファイルで段階的に読ませる

元記事では、Skill をフォルダとして扱い、SKILL.md から必要なファイルへ誘導する話も出てきます。これは Progressive Disclosure（段階的な読み込み）です。

たとえば、最初から SKILL.md に長い API リファレンスや検証チェックリストを全部書かない。

my-skill/
├── SKILL.md

SKILL.md は入口。細かい関数例は references/、実行できる検証は scripts/、成果物のひな形は assets/ に逃がす。agent は最初から全部を読まずに済みます。

配布と測定まで見る

元記事は、作った Skill をどう配るか、どう測るかにも触れています。

小さいチームなら repo に入れる。規模が大きくなるなら plugin / marketplace のような形で、使う人が選べるようにする。ここは「作った Skill をどこまで常時見せるか」の話でもあります。

測定も元記事で扱っています。Anthropic では PreToolUse hook を使って Skill の利用状況をログ化し、よく使われる Skill や期待より呼ばれていない Skill を見ている、と紹介されていました。

GitHub Copilot 側でまったく同じ仕組みを使う、という話ではありません。それでも、次の観点はそのまま使えます。

  • その Skill は呼ばれているか
  • 呼ばれたあとに成功しているか
  • description が弱くて見つかっていないだけではないか

Skill は作って終わりではなく、呼ばれ方を見るところまで含めて運用です。

自分の Skill を見直すメモ

自分の Skill では、まずこの 5 点を見ます。

1. description は人間向けの要約にしない

Skill の description は、README の概要欄ではありません。モデルが「この Skill を呼ぶべきか」を判断するための入口です。

description には、きれいな説明よりも、発火してほしい言葉を入れます。

ここでは、私が作った review-security-structure という Skill を例にします。
コードのセキュリティレビューを、ソースを端から読む前に AST / call graph / source-sink flow などの構造から絞り込むための Skill です。

---
name: review-security-structure
description: Use when reviewing code for vulnerabilities, SAST triage, source/sink flow, AST-based security review, or structural security hotspots.
---

これなら、ユーザーが security review や SAST triage と書いたときに見つかりやすくなります。

2. 落とし穴を Gotchas に残す

Gotchas は、作業中に踏みやすい落とし穴やハマりどころのことです。Skill の中では、「一般的な正解」よりも「この作業で毎回つまずく点」を残す場所として使います。

Anthropic の記事では、この Gotchas section が高シグナルだと書かれていました。

Skill には、一般論より「PowerShell で Bash heredoc を使わない」のような失敗例を置きます。

私の環境では、次のようなハマりどころを Gotchas に残します。

  • PowerShell で Bash heredoc を使わない
  • PowerPoint が開いている PPTX は COM Automation で編集する
  • GitHub CLI が private repo を見失ったら GH_TOKEN / GITHUB_TOKEN の上書きを疑う
  • 長い検証コマンドは stdout だけで完了判定しない

失敗メモを常時 instructions に全部載せると重くなります。対象タスクの Skill に置けば、毎回の説明を減らせます。

3. SKILL.md を太らせすぎない

この考え方自体は、今回の記事で初めて知ったわけではありません。

私も以前から、SKILL.md を太らせすぎると結局 instructions の過積載と同じ問題になる、という感覚はありました。実際、skill-creator-plus でも「入口は薄く、詳細は references/ や scripts/ に逃がす」という方針はすでに取り込んでいました。

ただ、Anthropic の記事を読んで、この方針にもう少し自信が持てました。SKILL.md を全部入りの手順書にするのではなく、agent が最初に読む入口として扱う。これは、自分の運用で感じていたこととかなり重なります。

詳細はフォルダの中で分けます。

my-skill/
├── SKILL.md
├── references/
│   ├── gotchas.md
│   └── api-examples.md
├── scripts/
│   └── verify.ps1
└── assets/
    └── report-template.md

SKILL.md は入口にして、細かいリファレンスやテンプレートは必要なときだけ読ませる。これは VS Code の Agent Skills docs でも progressive loading として説明されています。

入口を薄くして、必要な資料を近くに置く。私の copilot-instructions.md / Agents.md 過積載問題ともつながる話でした。

4. 検証を手順に入れる

Skill に「作る手順」だけを書くと、最後が弱くなりがちです。

次からは、最初から検証まで入れます。

  • 何を見れば完了か
  • どのコマンドを実行するか
  • 成果物のどこを確認するか
  • 失敗したらどこまで戻るか

UI、PPT、記事、GitHub Actions まわりは、検証 Skill から整えて手戻りを減らします。

5. 使用状況を測る

Anthropic の記事では、PreToolUse hook を使って Skill 使用状況をログ化している話も出ていました。

私の環境では、使用状況の記録はまだ未整備です。Skill が増えてくると、「作ったけど呼ばれていない」「呼ばれるけど毎回失敗する」が見えなくなります。

元記事で明確に書かれているのは、PreToolUse hook で Skill usage をログ化し、人気の Skill や期待より発火していない Skill を見ている、というところまでです。

GitHub Copilot Hooks 自体の考え方は、前に その commit、本当に安全？ コーディングエージェント時代に Git Hook で情報流出を防ぐ方法 でも整理しました。この記事では、そのうち「Skill の使用状況をどう測るか」に絞って考えます。

一方で、「候補になったけれど選ばれなかった回数」をどう測っているかまでは、本文では詳しく説明されていません。ここは自分の環境に置き換えるなら、次の 2 種類のログに分けるのが分かりやすいと思いました。

  1. 候補ログ: userPromptSubmitted で、依頼文から「この Skill が使われそう」と記録する
  2. 実使用ログ: Skill の中で必ず通る script / MCP tool / wrapper CLI の入口で、skill 名 と結果を記録する

つまり、使用率を出したいなら、こう考えます。

使用率 = 実使用ログの回数 / 候補ログの回数

ここで大事なのは、「Copilot が内部でどの Skill を選んだか」を hook だけで完全に当てにいかないことです。候補ログはあくまで近似です。そのうえで、Skill が実作業に入る入口を 1 つ決めて、そこを通ったら実使用として数える 方が、運用上は分かりやすいです。

流れを図にすると、次のようなイメージです。短く書くと、User prompt → 候補ログ → Skill の入口 wrapper → 実使用ログ → 使用率集計 です。

GitHub Copilot Hooks で Skill 使用率を測る流れ

たとえば review-security-structure なら、security review や SAST のような語を含む依頼を候補として記録する。実際に Skill の手順内で scripts/review-security-structure.ps1 を通ったら、skill: "review-security-structure" と result: "completed" / "blocked" を logs/skill-usage.jsonl へ追記する。

ここでいう blocked は「Skill が呼ばれなかった」ではありません。入口まで来たけれど、対象ファイルがない、必要な権限がない、検証コマンドが失敗した、のようにワークフローとして最後まで進めなかった状態です。

これで、「候補には上がったが使われなかった Skill」と「実際に作業まで進んだ Skill」を分けて見られます。完全な内部選択ログではありませんが、description が弱くて発火していない Skill や、呼ばれるけれど失敗しがちな Skill を見つけるには十分使えそうです。

まずは、次のような棚卸しから始めます。

見るもの 目的
Skill 名 ユーザーが探す動詞から始まっているか
description 発火条件が具体的か
Gotchas（落とし穴） 実際の失敗から育っているか
検証手順 完了判定まで書いてあるか
references / scripts SKILL.md に詰め込みすぎていないか

実際に作るときは Skill Creator+ を使う

ここまで読むと、「じゃあ自分の Skill をどう作ればいいの？」となります。

私の環境では、ここを skill-creator-plus に寄せています。これは、Anthropic 公式の Skill Creator を参考にしつつ、自分の運用で踏んだ落とし穴を足した Skill です。

skill-creator-plus では、最初に「本当に Skill でよいのか？」を確認します。1 回だけ使う slash task なら Prompt、常時守る方針なら Instruction、人格や tool 制限が主役なら Agent、決定論的に止めたい処理なら Hook。Skill は、scripts / references / assets を一緒に持つ再利用 workflow のときに選びます。

今回の Claude Code の記事を読んで、skill-creator-plus 側にも次の観点をより強く入れました。

  • description は人間向けの紹介文ではなく、モデルが呼び出し判断に使う入口として書く
  • Skill は 1 つの用途カテゴリに寄せ、複数カテゴリをまたいで太らせない
  • SKILL.md には自明な手順を増やすより、Gotchas、参照ファイル、scripts / assets の所在を書く
  • 詳細は references/ に逃がし、入口は軽く保つ

Skill を増やすほど、「作るための Skill」が効いてきます。自分の記憶だけで毎回判断すると、その日の気分で構造が変わります。作成・レビューの入口を skill-creator-plus に固定しておくと、少なくとも迷う順番はそろえられます。

作って、使って、Skill を改善する

今回の記事を読んで、私の中でいちばん整理されたのはこの 3 ステップです。

  1. skill-creator-plus で小さく作る
  2. 実際の作業で使う
  3. 失敗や検証結果を Gotchas / references / scripts に戻す

ここで大事なのは、Skill を「完成品」として置いておかないことです。最初から完璧な SKILL.md を作ろうとすると、だいたい太ります。まず薄く作って、実際に使って、詰まったところだけ戻す。この循環が現実的です。

私の環境では、学びを戻すときに retro-user、retro-workspace、retro-private-skills のような retro 系 prompt / skill を使います。いきなり SKILL.md に追記するのではなく、「これは User Data の instruction に戻すのか」「workspace の設計資産に戻すのか」「private skill repo の既存 Skill に戻すのか」を切り分けます。

これは Skill だけの話ではありません。prompt、instruction、agent、hook、記事用 workflow など、AI に渡す設計資産はどれも「一度作って完成」ではなく、使いながら改善して育てるものだと思います。うまくいった手順、失敗した判断、毎回聞き直している前提を、次に使える形へ戻す。その小さな積み重ねが、AI エージェントとの作業を少しずつ安定させてくれます。

参考: よかったら使ってみてください

なお、Skill を探したり、VS Code 上でインストール済み Skill を管理したりするところは、本筋というより補助ツールの話です。私が自分用に作って育てている Skill や拡張機能もあるので、合いそうなら使ってみてください。

VS Code で Skill だけを扱う場合は、Agent Skill Ninja が便利です。もともとは skill-finder という私のお手製 Skill から始まり、検索やインストール、AGENTS.md / copilot-instructions.md の同期を拡張機能側に寄せたものです。

2026/06/06 時点では、VS Code Marketplace 上で 1,279 installs まで使ってもらえるようになっていました。ありがたいです 🙏

Agent Skill Ninja の VS Code Marketplace 表示。2026/06/06 時点で 1,279 installs

Skill だけでなく、agents、prompts、instructions、hooks、MCP config まで含めて管理したい場合は Agent Resources Ninja もあります。ただ、Agent Resources Ninja は扱う範囲が広いぶん、まだ少し微妙なところもあります。現時点で Skill だけを安定して扱いたいなら Agent Skill Ninja の方が分かりやすいです。Agent Resources Ninja は、興味がある方に「よかったらどうぞ」くらいの温度で置いておきます。

この記事を読んだ後の私の結論

今回の Claude Code の記事は、GitHub Copilot 側の Skill 設計にもそのまま持ち込めます。

VS Code の GitHub Copilot でも Agent Skills が使えるようになり、Copilot CLI や Copilot cloud agent へ持ち回せます。Skill は「便利な追加指示」より、作業の単位として扱う場面が増えます。

次は、既存の Skill を 9 カテゴリで棚卸しします。

  • 検証系 Skill が足りているか
  • description が発火条件として機能しているか
  • Gotchas（落とし穴・ハマりどころ）が実体験から育っているか
  • SKILL.md に詰め込みすぎていないか
  • instruction に置くべき内容と Skill に逃がす内容が分かれているか

この棚卸しで、AI エージェントとの作業を落ち着かせます。

良い Skill も最初は数行と 1 つの Gotcha から始まっていた。エッジケースに当たるたびに育てればいい。

小さく作って、失敗したら retro 系 prompt / skill で反映先を決める。Gotchas（落とし穴）に足すもの、references に逃がすもの、scripts にするものを分ける。何度も使うなら共有する。

私はこの粒度で始めます。頑張るぞ～ 💪

参考 / 出典

4
3
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
4
3

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?