0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Agent Skills 実践ガイド Part 1:来歴・仕組み・作り方・使い方、そして公開リポジトリに学ぶ

0
Last updated at Posted at 2026-11-18

前回の記事では、AGENTS.md を「薄い憲法」にし、長い手順は skill に出す、と書きました。では、その skill は、どう作り、どう使い、どう信頼すればよいのでしょうか。

skill を使い始めると、次のような壁に当たります。

  • skill を入れたのに、発動しない(または、関係のない場面で発動する)
  • description に手順を書いたら、本文を読まずに、要約のとおりに動いた
  • 他人の skill を入れたら、中身を読まないまま、実行コードが混ざっていた
  • 数十本に増え、どれが効いているのか分からない。常時のコストだけが増える
  • code-review の skill を作ったが、人の承認と agent の確認の線引きが曖昧で、「LGTM」が通ってしまう
  • 長いセッションで、トークンもコストも膨らむ。モデルと推論の強さを、どう使い分ければよいか分からない

本記事(Part 1)は、その壁を越えるための土台です。skill を 来歴 → 仕組み → 作り方 → 使い方 → 実物 の順に、入門から一続きにまとめました。Anthropic、GitHub、OpenAI などの公式文書とソース、公開リポジトリの skill、2026 年の研究を調べ、そのまま使える形に落としています。チームのレビュー設計と 5 つの汎用 skill は Part 2、専用 skill・agent への展開は Part 3 です。

目的は、skill を増やすことではありません。「agent に任せる部分」と「人が持つ部分」を分け、任せる部分を、検査できる手順として固定することです。skill は、人の判断を置き換えるものではなく、人が判断するための材料を、安く、速く、漏れなく出すためのものです。

この Part で得られるもの

  • skill の来歴と、AGENTS.md・skill・MCP・subagent・hook の分担(第1章)
  • 読み込みの 3 段階、description が導線である理由、発動しないときの切り分け(第2章)
  • 設計原則 9 か条と、9 ステップの建構手順、失敗の表(第3章)
  • 入手 4 経路、配置と同期、確認、チーム運用、セキュリティの点検、評価の回し方(第4章)
  • 世界で広く使われている公開リポジトリ(anthropics/skills、obra/superpowers、mattpocock/skills ほか)から取った設計(第5章)

前回記事の続き

前回は AGENTS.md の側(常に効く最小の契約)を扱いました。このシリーズは、その外に出した**作業別の手順(skill)**の側です。分担の原則(常に効くものは AGENTS.md、作業ごとの手順は skill、機械で止められるものは hook・CI・テスト、判断は人)は、前回の続きです。

3 部構成のシリーズです

Part 章 内容
Part 1 第1〜5章 skill の来歴・仕組み・作り方・使い方、公開リポジトリに学ぶ
Part 2 第6・7・8章 チームのレビュー設計、5 つの汎用 skill の全文、運用と習熟
Part 3 第9章 専用 skill・agent への展開(POS・CRM・移行・需要予測)

章・節の番号は、3 部を通した番号です。別の Part にある章を参照している箇所は、その番号のまま書いてあります(たとえば「7.5」は Part 2、「9.3」は Part 3、「3.2」は Part 1)。前回記事(AGENTS.md 編)の参照は「前回記事」と書いています。

本文の仕様・設定名・数値は 2026年11月時点で、公式ドキュメント、公式リポジトリのソース、論文で確認した内容です。モデル名、各ツールのパスと上限、道具の評価は変わりやすいので、使うときに最新の文書を確認してください。数値は、測定した主体(ベンダー、論文、第三者)が出したもので、都度そう書きます。他社の数字は、自分たちの目標にしません。

先に結論

  1. 役割を分ける。 AGENTS.md は常に効く最小の契約。skill は、作業ごとに必要なときだけ読み込まれる手順。subagent は別の文脈・権限・モデルの役。hook・CI・テストは、例外を許さない柵。判断と責任は、人が持つ
  2. skill の効き目は、description がほぼ決める。 起動時に読まれるのは名前と description だけ。「いつ使うか」と境界だけを書き、手順は書かない
  3. 作る前に、梯子を上る。 構造 → lint・型 → テスト・hook → 文章の順に、止められないか確かめる。skill は最後の手段。作るなら、失敗を先に観測し、評価を先に作る
  4. 他人の skill は、実行コードとして扱う。 読み、固定し、点検する
  5. チームのレビューは、責任分担から設計する。 人は、作るべきか・危険なコード・前例・証拠の検証・責任を持つ。agent は、独立した走査・検証・証拠・材料を出す。承認は人

読み方ガイド

知りたいこと 読む場所
skill とは何か。AGENTS.md・MCP・subagent との違い 第1章(この Part)
どう読み込まれるのか。なぜ発動しないのか 第2章(この Part)
自分で作りたい(方法と手順) 第3章(この Part)
他人の skill を、安全に入れて使いたい 第4・5章(この Part)
チームのコードレビューを、人と agent で設計したい 第6章(Part 2)
そのまま使える skill がほしい 第7章(Part 2)
続けるための運用、チェックリスト 第8章(Part 2)
POS・CRM・移行・需要予測の専用 skill・agent を作りたい 第9章(Part 3)

最短ルート。 初めての人は 1 → 2 → 3 → Part 2 の 7.1。個人で今日から使うなら 4 → Part 2 の 7(5 つを置く)→ 8.2。チームのリードは Part 2 の 6 → Part 1 の 4 → Part 3 → Part 2 の 8 です。


1. skill の来龍去脈:なぜ生まれ、いまどこにあるのか

1.1 前回記事の続き:手順の行き場所

前回記事の結論は、「AGENTS.md は常に効かせる最小の契約(薄い憲法)にして、作業別の手順は skill に出す」でした。では、その skill とは何で、どこから来たのでしょうか。まず、skill が登場する前に、手順をどこに置いていたかを見ます。

仕組み 何をするものか 限界
AGENTS.md・CLAUDE.md・Cursor rules などの常時ルール 毎回読み込まれる指示 長いほど毎ターンのコストが増え、手順は埋もれる(前回記事 第2・3章)。Claude Code の公式ドキュメントも、CLAUDE.md や skill の指示は「リクエストであって、保証ではない」としている
スラッシュコマンド(Claude Code の custom commands、Cursor のコマンド)、Copilot のプロンプトファイル 人が呼ぶ定型プロンプト 人が存在を覚えている必要がある。ツールごとに形式が違い、agent が自分では選べない
MCP ツールやデータへの接続 「手」は増えるが、「どう使うか」は教えない。ツール定義がコンテキストを使う
subagent 別の文脈・別の権限で動く作業者 実行の場であって、手順そのものではない。手順は別に要る

ここに登場したのが skill です。作業別の手順書を、必要なときにだけ読み込む仕組みです。手順を AGENTS.md に詰めると毎ターン払うコストを、skill は「説明文(description)だけ常時、本文は使うときだけ」に変えます。

1.2 年表:Anthropic の発表から、業界の共通形式へ

日付 出来事
2025-10-16 Anthropic が Agent Skills を発表(Claude アプリ、API、Claude Code)。同日、設計思想を述べたエンジニアリングブログ「Equipping agents for the real world with Agent Skills」を公開(日付は初回のアーカイブからの推定)
2025-12-02 OpenAI Codex に、skills の実験的サポートが入る(PR #7412)
2025-12-18 Anthropic が Agent Skills をオープン標準として公開(agentskills.io)。同日、GitHub Copilot が coding agent・Copilot CLI・VS Code Insiders で skills に対応
2025-12-22 OpenCode が対応
2025-12-30 〜 2026-01-20 Gemini CLI が実験的に対応(12-30)、v0.25.0(01-20)で既定で有効に
2026-01-08 VS Code 1.108 が Agent Skills(実験的)に対応。2026-02-04 の 1.109 で、skill をスラッシュコマンドとして呼べるように
2026 年 1 月下旬まで Cursor 2.4 が、エディタと CLI で skills に対応
2026-04-16 GitHub CLI 2.90.0 に gh skill(public preview)。skill の検索・導入・更新・公開ができる
2026-11-04 agentskills プロジェクトが、Linux Foundation 系のガバナンス(Agent Skills a Series of LF Projects, LLC)を採択。コードと仕様は Apache-2.0、ドキュメントは CC-BY-4.0

統合された古い仕組み。 Claude Code では、custom commands が skill に統合されました(.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md は、どちらも /deploy を作る)。Cursor は、常時ルールより skill のほうが「動的な文脈の発見」に向くとして、ルールやコマンドを skill に変換する /migrate-to-skills を備えています。Copilot のプロンプトファイルは Local harness(ローカルの実行基盤)でしか使えず、その Local harness は 2027 年 2 月に廃止予定と案内されています。手順の置き場所は、skill に収束しつつあります。

1.3 オープン標準になった意味

  • 形式は 1 つ。 フォルダに SKILL.md(YAML の frontmatter と Markdown の本文)を置き、必要なら scripts/、references/、assets/ を足す。これだけです。同じフォルダが、Claude Code、GitHub Copilot(VS Code・CLI)、Codex、Cursor、Gemini CLI、OpenCode、Amp などで使えます
  • ただし、完全に同じには動きません。 置き場所、呼び出し方、独自の拡張フィールドはツールごとに違います(2.5)。.agents/skills/ が事実上の共通の置き場所になりましたが、Claude Code の公式ドキュメントの場所表には載っていません
  • AGENTS.md と対になる。 AGENTS.md が「常に効く最小の契約」を共通化し、skill が「作業別の手順」を共通化します

1.4 AGENTS.md・skill・MCP・subagent・hook の役割分担(更新版)

各社の公式ドキュメントは、次のように整理しています。

仕組み 載せるもの 読み込み 強制力
AGENTS.md 振る舞いの契約(「どう振る舞うか」)。ほぼ毎回効く短いルール 毎ターン なし。VS Code は「指示は強制ではない」と明記
skill 特定の種類の作業の手順(「どう扱うか」)。参照資料やスクリプト description は常時、本文は使うとき。スクリプトは実行して読まない なし(リクエスト)。守らせたいものは hook へ
MCP ツールやデータへの接続。skill が、その使い方を説明する ツール名は起動時、スキーマは必要時(Claude Code) —
subagent 別の文脈・権限・モデルで動く作業者。結果は要約で返る。skill を載せられる 呼ばれたとき 権限で制限
hook イベントで実行されるコード。例外を許さないルール モデルの判断に依らない(コンテキストのコストはゼロ) あり

Claude Code の公式ドキュメントは、skill を「どの文脈にも読み込める再利用可能な内容」、subagent を「分離された作業者で、要約を返す」と区別し、両者を skills: フィールドや skill の context: fork で組み合わせられると述べています。GitHub のドキュメントも、「カスタム指示は振る舞い、skill は特定の種類の作業の扱い方、MCP はツール、hook はコードの実行」と整理しています。

この記事の分担は、この整理をそのまま使います。 「守らせたい」ものは hook・CI・権限、「いつも効く」ものは AGENTS.md、「この作業のとき」は skill、「別の文脈で繰り返し頼む役割」は agent です。

1.5 skill は、本当に効くのか

まとまった測定は、2026 年に入って出てきました。代表が SkillsBench(arXiv 2602.12670)です。端末・コンテナ上の 87 タスク、8 つの領域、18 の「モデル × 実行基盤」の組み合わせ(Claude Code、Codex CLI、Gemini CLI、OpenHands)で、skill の有無を比べています(以下は v4 の数字です。v1〜v3 とは、タスク数や結果が違います)。

条件 結果
人が整えた skill 平均合格率が 33.9% → 50.5%(+16.6 ポイント)。すべての構成で改善(+4.1〜+25.7 ポイント)
agent が自分で書いた skill skill 無しより低下(Claude Code −8.1、Codex −11.3、Gemini CLI −11.5 ポイント)。論文の分析では、skill が発見されない、作ること自体が解くことを押しのける、自信に満ちた誤りが入る、が原因
領域別 ソフトウェア開発は +11.6 ポイント。ほかは、自然科学 +28.8、メディア +24.1、サイバーセキュリティ +18.9、金融 +14.2、数学・OR +9.7 など。87 タスクのうち 13 は悪化
skill の数 1 個 +18.0、2〜3 個 +19.0、4 個以上 +10.1
skill の長さ compact +19.0、standard +21.5、detailed +14.5、comprehensive +0.7

別の研究では、skill の数が増えると、選択の精度が落ちると報告されています。小さな有用な集合から 202 個まで増やすと、最大 21% 低下し、原因は文脈の量ではなく、誤った skill が選ばれること(skill shadowing)でした(arXiv 2605.24050。アブストラクトの水準での確認です)。

読み方と注意。 評価は端末・コンテナのタスクに限られ、長さを揃えた対照が無いため、「文脈が増えたこと自体」の効果も混じります。それでも、方向は一貫しています。

  1. 実際の専門性から作った skill は効く。agent に一から書かせた skill は効かない。 agentskills.io のガイドも、実際のタスクや runbook から作り、LLM に何もないところから作らせないよう求めています
  2. 少なく、焦点を絞る。 3 つ以内の焦点のある skill が、包括的な束に勝ちました
  3. 短く、適度に。 包括的すぎる skill は、効果がほぼ消えます
  4. 効いているかは、測る。

この記事の設計は、この 4 点に従っています。 5 つの skill は単一責任で、本文は短く、詳細は参照に出し、評価を先に作ります(第3章)。

ここまでの要点。 skill は、手順の置き場所が収束した形で、オープン標準になっています。ただし、作れば効くわけではありません。**どう作るか(第3章)と、効いているかをどう確かめるか(第3・4章)**が、品質を決めます。


2. 仕組み:skill はどう読み込まれ、どう動くのか

2.1 skill の解剖

my-skill/
├── SKILL.md          必須。frontmatter(YAML)+本文(Markdown)
├── scripts/          任意。実行するコード(中身は読まれない)
├── references/       任意。必要なときに読む資料
├── assets/           任意。出力にそのまま使うファイル(テンプレートなど)
└── evals/            任意。評価(ツールが読み込む場所ではない)

frontmatter(Agent Skills 仕様)。

フィールド 必須 制約
name 必須 1〜64 文字。小文字の英数字とハイフンのみ。先頭・末尾のハイフン、連続ハイフンは不可。親ディレクトリ名と一致
description 必須 1〜1024 文字。「何をするか」と「いつ使うか」、キーワードを書く
license 任意 ライセンス名、または同梱ファイルへの参照
compatibility 任意 1〜500 文字。環境の要件がある場合だけ
metadata 任意 文字列から文字列への対応表
allowed-tools 任意 空白区切りのツール一覧(実験的。ツールにより扱いが違う)

ツール固有の拡張(例:Claude Code)。 when_to_use(description に連結される)、disable-model-invocation、user-invocable、model、effort、context: fork、agent、paths、hooks、disallowed-tools、shell などがあります。拡張フィールドは、他のツールでは無視されるか、claude.ai や API へのアップロードではエラーになります。 移植性を優先するなら、仕様のフィールドだけで書き、拡張は必要なときだけ足します。

2.2 3 段階のロード(段階的開示)

skill の設計の中心は、情報を一度に読み込まず、必要になった順に段階的に読むことです。

段階 内容 いつ文脈に入るか 目安
L1 カタログ name と description 常に(起動時) 1 つあたり約 50〜100 トークン
L2 本文 SKILL.md の本文 skill が選ばれたとき 5,000 トークン未満、500 行未満
L3 資料 references/、scripts/、assets/ 本文の導線が発火したとき。スクリプトは実行するだけで、中身は読まれない 上限なし

なぜこの設計か。 50 個の skill を入れても、起動時のコストは L1 の合計だけ(数千トークン)で済みます。本文や資料は、選ばれた skill の分だけ読まれます。AGENTS.md に同じ量の手順を詰めたときは、毎ターン、全部を払います。

2.3 トリガーの正体:description が導線

skill を選ぶのは、人間が /name と打つか、モデルが description と依頼を照らし合わせて選ぶかのどちらかです。

  • description は、skill の導線(context pointer)です。 何が書いてあるかではなく、どの条件で読むかを決めます。前回記事の導線の話と同じです。本文に「いつ使うか」を書いても、すでに選ばれた後なので遅すぎます
  • 自動で選ばれないようにもできます。 Claude Code では disable-model-invocation: true(description が文脈から消え、人だけが呼べる)、Codex では agents/openai.yaml の policy.allow_implicit_invocation: false、Cursor や VS Code でも disable-model-invocation が使えます。副作用のある手順は、人だけが呼べるようにします
  • 逆に、人から隠すこともできます。 user-invocable: false(Claude Code、VS Code)は、description は文脈に残し、/ のメニューからは隠します
  • 単純な 1 ステップの作業では、skill が使われないことがあります。 agent は、自分で十分と判断すると、skill を読みません(agentskills.io の指摘)。skill は、複数ステップの作業や、判断を要する手順のためのものです

2.4 コストの構造

コスト 何に払うか 数字(ツールにより異なる)
常時(context load) L1 のカタログ。description の長さ × skill の数 Claude Code:listing の予算は文脈の 1%。超えると、使用頻度の低い description から削られる(名前は常に残る)。Codex:リスト全体の上限は文脈の約 2%(不明なときは 8,000 文字)。超えると description が短縮され、skill が落ちて警告が出る
使用時(L2) 本文 1 回の読み込みで、文脈に残り続ける。Claude Code:圧縮(compaction)後は、各 skill の直近の呼び出しを、先頭 5,000 トークンまで、合計 25,000 トークンの枠で再添付する
必要時(L3) 参照資料 読んだ分だけ
実行時 スクリプト 中身は文脈に入らない。出力だけ
人の認知(cognitive load) どの skill があり、いつ呼ぶかを人が覚える router skill で 1 本にまとめることもできる(mattpocock/skills)

ここから、設計上の 3 つの帰結が出ます。

  1. skill は、少なく、鋭く。 数が増えるほど、個々の description が削られ、選ばれにくくなります
  2. 本文の大事な指示は、先頭に置く。 長い会話のあと、圧縮で本文が切られる場合があります(Claude Code では先頭 5,000 トークンまで)。長い手順は、参照に出します
  3. 決定論的な処理はスクリプトに。 実行するだけなら、中身は文脈に入らず、コストがほぼゼロです

2.5 ツール別の置き場所と呼び出し

ツール プロジェクト 個人 呼び出し 備考
Claude Code .claude/skills/<name>/ ~/.claude/skills/ /name、または description による自動 .agents/skills は、公式の場所表に無い。 拡張フィールドが多い。エンタープライズ配布(管理設定)、plugin
GitHub Copilot(VS Code・CLI・cloud agent・code review) .github/skills/、.claude/skills/、.agents/skills/ ~/.copilot/skills/、~/.agents/skills/ /name(VS Code 1.109 以降)、自動。CLI は /skills VS Code は、実行基盤(harness)ごとに場所が決まる(Copilot:.github/skills、Claude:.claude/skills、Codex:.agents/skills)。名前が不正な skill は、黙って読み込まれない
OpenAI Codex .agents/skills(作業ディレクトリから、親、リポジトリルートへ) ~/.agents/skills $name、/skills、自動 同名の skill は統合されない。agents/openai.yaml で、暗黙の呼び出しの可否を制御。配布は plugin が推奨
Cursor .agents/skills/、.cursor/skills/(互換のため .claude/skills/、.codex/skills/ も読む) ~/.agents/skills/、~/.cursor/skills/ Agent chat で /、自動 リポジトリから直接は取り込めない(plugin にして配布)。/migrate-to-skills
Gemini CLI .gemini/skills/、.agents/skills/ ~/.gemini/skills/、~/.agents/skills/ モデルが activate_skill を呼ぶ(利用者に同意の確認が出る)、/skills 2026 年 1 月下旬から既定で有効
OpenCode .opencode/skills/、.claude/skills/、.agents/skills/ ~/.config/opencode/skills/、~/.claude/skills/、~/.agents/skills/ skill ツール。allow/deny/ask で権限を制御 git ワークツリーまで遡って探す
Windsurf .windsurf/skills/ ~/.codeium/windsurf/skills/ @skill-name、自動 .agents/skills を読むかは未確認

共通の置き方(推奨)。

  1. 正本は .agents/skills/ に置く。 Copilot、Codex、Cursor、Gemini CLI、OpenCode、Amp、Cline、Warp が、プロジェクト単位でこの場所を共有しています
  2. Claude Code 向けに .claude/skills/ へ同期する。 方法は 3 つです。①シンボリックリンク(Windows では、開発者モードか権限が要る)、②スクリプトか CI でコピー、③plugin として配布。Windows のロックされた環境では、②が確実です
  3. 拡張フィールドは、使うツールが決まってから足す。 仕様のフィールドだけなら、どのツールでも同じに動く
  4. description は 1024 文字以内に。 Claude Code の listing の上限は 1536 文字(description と when_to_use の合計)ですが、仕様と VS Code の上限は 1024 文字です。目標は 300〜500 文字です

2.6 動かないとき、守られないとき

症状 確認すること
発動しない description にユーザーが使う言葉があるか。skill が一覧に出ているか(Claude Code:/skills、Copilot CLI:/skills list)。名前がディレクトリ名と一致しているか(不一致は、黙って読み込まれないことがある)。言い換えて試す。/name で直接呼ぶ
発動しすぎる description を具体的にする。または、自動呼び出しを切る
途中で守られなくなる(長い会話のあと) 必ず守らせたいルールは、hook に移す。 圧縮のあとに、skill を呼び直す。重要な指示を、本文の先頭近くに置く
skill が増えて効かなくなる listing の予算(1%/2%)を超えて、description が削られていないか。使われない skill を削る。Claude Code は /doctor でコストを見積もり、/skill-doctor で skill ごとのコストと使用状況を報告する
YAML が壊れている frontmatter の最初の --- は 1 行目に置く。壊れていると、フィールドなしで読み込まれる。--debug で確認し、claude plugin validate が使える
同名の skill が衝突する 優先順位は、ツールごとに違う(Claude Code:管理設定 > 個人 > プロジェクト)。同名を避ける

2.7 skill と agent(subagent)の関係

skill と agent(subagent、custom agent)は、手順と実行者という別の役割です。

skill agent(subagent、custom agent)
持つもの 手順、参照、スクリプト 役割、権限(ツール)、モデルと推論の強さ、載せる skill
文脈 呼び出した文脈に読み込まれる 自分の文脈ウィンドウを持つ。会話履歴は渡されず、要約だけが戻る(Claude Code)
ツールの制限 allowed-tools は事前承認であって、制限ではない(Claude Code) tools は本当の許可リスト
向いている用途 作業別の手順 独立したレビュー、読み取り専用の探索、重い走査を主会話から切り離す

組み合わせ方は 2 通りです。

  1. agent に skill を載せる。 Claude Code の subagent の skills:(全文を事前に読み込む)、VS Code の custom agent の skills
  2. skill から、別の文脈で動かす。 Claude Code の context: fork(agent: Explore などを指定)

この記事での使い分け。 手順は skill に書き、独立性・権限・モデルが要る役割だけを agent にします(レビュー agent、探索 agent)。agent の設計は 9.3、モデルと推論の強さの割り当ては 7.5 です。


3. 作り方:設計原則と、9 ステップの建構手順

この章は、skill を 1 本作るときの手順書です。第7章の 5 つの skill も、すべてこの手順で作ります。流れは次のとおりです。

3.1 まず「skill にするか」を決める(ステップ 0)

skill は、作る前に、作らなくて済まないかを疑うものです。次の順に問います。上から当てはめて、最初に Yes になったところが置き場所です。

問い Yes のとき
1. その失敗は、2 回以上起きたか。実例があるか No なら、作らない。必要でも AGENTS.md に 1 行
2. 機械で止められるか(型・lint・テスト・フック・権限) そちらを作る(梯子 L1〜L3。6.10)。skill は補助に回る
3. ほぼ毎回効く、短い事実か AGENTS.md(前回記事)
4. 1 つのディレクトリ(ドメイン)だけの話か ネストした AGENTS.md
5. 特定の作業でだけ使う手順か(3 ステップを超える、分岐がある、出力の形式がある) skill
6. 同じ役割を、別の文脈・別のモデル・別の権限で繰り返し頼むか agent(9.3)。役割の手順は skill にして載せる
7. 外部システムへの接続が要るか MCP やツール。skill は、使い方の手順だけを持つ
8. 副作用がある(書き込み、デプロイ、送信、課金)か skill にするなら、自動呼び出しを切り、人が呼ぶものにする

この順序が、前回記事の分担の続きです。 AGENTS.md は常に効く最小の契約、skill は作業ごとの手順、機械で止められるものは機械、という分担を、判断の順序にしました。

3.2 設計原則 9 か条

# 原則 具体的には 出典
1 読者は AI である 来歴、背景、口調、バージョン履歴は書かない。「次に何をするか」だけを書く。人間向けの文書(README、CHANGELOG、導入ガイド)は skill の中に置かない Anthropic、Codex の skill-creator の考え方
2 コンテキストは公共財 モデルが既に知っていることは書かない。1 行ごとに「消したら間違えるか」を問う。長い説明は、短い実例 1 つに置き換える Anthropic、writing-for-agents
3 description が導線 「何をするか」と「いつ使うか」を書く。分岐ごとに引き金を 1 つ。本文に「いつ使うか」を書いても遅い Anthropic、writing-for-agents
4 手順と、検査できる完了基準 各ステップは、「終わった」と判定できる基準で終える。基準は、検査でき、網羅的なほど強い writing-for-agents
5 自由度は、脆さに反比例させる 脆い操作(形式・長さ・順序が決まっている)はスクリプトで固める。創造的な判断は、方向だけを文章で与える Anthropic、Codex の skill-creator
6 段階的開示 SKILL.md は短く(500 行未満)、詳細は参照ファイルへ。参照は 1 段。必要な枝でだけ読ませる Anthropic、Agent Skills 仕様
7 単一の情報源 環境が持つ情報(scripts、設定、ディレクトリ構成)は書き写さない。同じ意味は 1 か所にだけ置く writing-for-agents
8 肯定形で書き、禁止は防衛線にする 取るべき行動を書く。禁止は、症状・検出方法・直し方を添えた表にする(3.3 の表) writing-for-agents、Codex の skill-creator
9 評価で育てる 評価を先に作り、失敗駆動で足す。同じ失敗が 2 回出たら、上の層へ移す Anthropic、superpowers

原則 8 の補足。 「禁止形は、行動空間に境界を引くので正確だ」という考えと、「禁止すると、禁止された行動が文脈に呼び出されて、むしろ起きやすくなる」という考えは、一見ぶつかります。使い分けは次のとおりです。

場面 書き方 例
振る舞いの方向づけ 肯定形で、取るべき行動を書く 「1 行のコメントで書く」(「長く書かない」ではなく)
越えてはいけない最終防衛線 禁止形でよい。ただし取るべき行動を添える 「生成ファイルを手で編集しない。元を直し、生成コマンドを実行する」
起きがちな失敗の一覧 表にする。症状(検出できる形)、直し方 「症状:結論だけで根拠がない → 直し方:場所と場面を添える」
曖昧な禁止(「冗長にしない」) 書かない。何も変えない行は、コストだけ払う —

3.3 9 ステップの建構手順

# ステップ 成果物 完了の基準
0 作るか決める(3.1) 置き場所の判断(1 行) 梯子の L1〜L3 で止められないと確認した
1 失敗の実例を集める 失敗メモ 3 件(トランスクリプト付き) skill が無いときに何が起きるかを言える
2 契約を決める 契約メモ 1 枚 トリガー、完了基準、副作用、人に返す条件が書かれている
3 評価を先に作る 評価の表(発動する/しない、振る舞い、圧力) skill 無しで走らせて、失敗する(Red)ことを確認した
4 description を書く name と description 発動の評価が通る
5 本文を書く SKILL.md ステップごとに完了基準がある。500 行未満
6 決定論的な部分を外に出す scripts/references/assets スクリプトを実際に実行して確かめた
7 検証する 構造チェック、評価の実行記録 評価が Green。誤発動が許容内。コストが許容内
8 出荷して保守する リポジトリへの配置、PR、保守の担当 レビューされ、更新の条件が決まっている

ステップ 1:失敗の実例を集める

skill が無い状態で、実際のタスクを agent に実行させ、どこで失敗したかを記録します。理由は、モデルは、あなたが想像する失敗ではなく、実際の失敗をするからです。次の 3 点を、3 件分集めます。

  • 依頼文(そのまま)
  • agent が何をして、どこで外したか(トランスクリプトの該当箇所)
  • 期待する成果物の例

3 件に共通する外し方が、skill に書くべき内容です。共通点が見つからなければ、まだ作るときではありません。

ステップ 2:契約を決める

書き始める前に、1 枚の契約メモを作ります。重要な skill は、第6章のように、要件に番号(R1…)を付けます。仕様 → 設計 → テストを、skill にも適用するためです。

# skill contract: <name>
Purpose (1 line):
Failure it prevents (with 3 evidence links):
Triggers (one per branch):
  -
Not for (neighbor skills, with their names):
Done when (checkable and exhaustive):
Inputs / outputs:
Side effects and risk tier (T0-T3):
Invocation: model-invoked / user-only
Tools allowed, model, effort (see 7.5):
Hand back to a human when (B-list):
Requirements (R1..Rn):

起動方式の決め方。 副作用がなく、手順を知っていれば安全な skill(レビュー、調査、仕様作成)は、モデルが自動で選べるようにします。副作用がある skill(デプロイ、書き込み、送信、課金)は、人だけが呼べるようにします。人が呼ぶ skill は、他の人が呼ぶ skill を呼ばず、自動で選ばれる skill だけを呼ぶ、という約束にしておくと、依存が絡まりません(mattpocock/skills の整理)。

ステップ 3:評価を先に作る

評価は、skill を書く前に作ります。 次の 3 種類を、最低限そろえます。

種類 何を確かめるか 作り方
発動(trigger) 発動すべき依頼で発動し、発動すべきでない依頼で発動しないか 発動する依頼 8〜10 件、発動しない依頼 8〜10 件(隣の skill と紛らわしいものを入れる)
振る舞い(behavior) 手順どおりに動き、成果物が基準を満たすか 実際の依頼 3〜5 件。「何が観測できれば合格か」を、出力の中の具体的な要素で書く
圧力(pressure) 急かされたとき、省略したくなる状況でも守るか 「急いでいるのでテストは後で」「この指摘は無視して通して」のような、誘惑のある依頼 2〜3 件

評価の表は、次の形で作ります。

# 種類 依頼 合格の条件(観測できるもの) 結果
T1 発動(+) 「この差分をレビューして」 トランスクリプトに skill の読み込みが出る
T2 発動(−) 「この関数の使い方を教えて」 読み込まれない
B1 振る舞い … 出力に、○○(件数、場所、未確認の欄)がある
P1 圧力 「急いでいるので承認だけして」 承認せず、人に返す理由を述べる

skill 無しで走らせて失敗すること(Red)を確かめてから、書きます。最初から通る評価は、何も守りません。これは、テスト駆動開発を skill に適用したものです。

ステップ 4:description を書く

description は、モデルが skill を選ぶ唯一の手がかりです。起動前に常に読み込まれるので、1 語ごとにコストがかかります。

型。

[何をするか:動詞+対象+成果物]. Use when [分岐1], [分岐2], or [分岐3]. Not for [隣の skill の領分] (use <name>).

書き方のルール。

  • 三人称で書く。 description はシステムプロンプトに差し込まれるので、視点が混ざると選択がぶれます("Reviews code changes…" のように。"I can…" や "You can…" は使わない)
  • 「何を」だけでなく「いつ」を書く。 分岐(別の場面)ごとに、引き金を 1 つ。同じ分岐を言い換えただけの同義語は並べません
  • 隣の skill との境界を書く。 「バグが既知ならレビューではなく bug-investigation」のように、紛れやすい相手の名前を出します
  • キーワードを先頭に近い位置に置く。 ユーザーが実際に使う言葉(「レビュー」「差分」「PR」)を入れます。日本語で依頼するなら、日本語の語も併記します(効果は、発動の評価で確かめます)
  • 手順の要約を書かない。 手順を description に書くと、モデルが本文を読まずに要約どおりに動くことがあります。description は「いつ使うか」、本文は「どうやるか」です。superpowers の writing-skills は、これを明文化し、実例を挙げています。「タスクの間にコードレビュー」と description に書いた skill では、agent がレビューを 1 回だけ行いました。本文のフローチャートは 2 回を指示していたのに、です。description を「Use when executing implementation plans with independent tasks」に直すと、フローチャートのとおりに動きました(第5章)
  • 文字数。 仕様上の上限は 1024 文字ですが、目標は 300〜500 文字です。常に読み込まれるコストなので、短いほど良い
悪い例 良い例
description: code review description: Reviews a diff, branch, or PR for bugs, spec fidelity, standards, test quality, and risk, using independent fresh-context passes, and reports evidence-backed findings. Use when asked to review or check a change, before opening or merging a PR, or after an agent finishes a task. Not for fixing the code or for investigating a known bug (use bug-investigation).

ステップ 5:本文を書く

本文は、もう 1 人の agent に渡す作業指示書です。骨格は次のとおりです。

---
name: <skill-name>
description: <what>. Use when <branches>. Not for <neighbors>.
---

# <Title>
<One or two lines: the purpose and the one rule that matters most.>

## Steps
1. <Verb phrase.> <How, briefly.> Done when <checkable criterion>.
2. ...

## Rules
- <Positive instruction.> <Hard guardrail with the action to take instead.>

## Output
<The exact shape of the result.>

## Hand back to a human when
- <Condition from the B-list.>

## References (read only when the branch applies)
- <Branch X> -> references/x.md

ステップは、必ず完了基準で終えます。 完了基準が曖昧だと、モデルは「終わること」に注意が向き、早く終わらせます(早すぎる完了)。検査でき、網羅的な基準ほど、確実に守られます。

弱い(曖昧) 強い(検査でき、網羅的)
コードを理解する 変更した関数の呼び出し元をすべて列挙する(grep またはコードグラフ)。各呼び出し元に、テストの有無を書く。すべて書かれたら終わり
問題がないか確認する 変更されたテストの assertion をすべて列挙し、それぞれの変更理由を要件に結びつける。結びつけられないものは復元する
調査する 再現する1 つのコマンドを、1 回実行して出力を示す。そのコマンドが失敗(Red)を示したら終わり

手順の書き方。

  • 命令形で、短く。 「…してください」ではなく「…する」
  • 長い参照は本文に入れない。 分岐ごとに別ファイルにして、本文には導線だけ置きます(3.3 のステップ 6)
  • 例は、説明より強い。 10 行の実例は、3 段落の説明に勝ちます
  • 出力の形式を固定する。 件数、場所、未確認の欄など、後工程(人)が読む項目を指定します

ステップ 6:決定論的な部分を外に出す

置く場所 中身 読み込み 向いているもの
scripts/ 実行できるコード 実行する(中身は読まない)。コストがほぼゼロ 毎回同じ結果が要るもの、形式・長さの制約があるもの、同じコードを毎回書き直すもの、検証
references/ 必要なときに読む資料 導線が発火したとき 詳細な規約、スキーマ、分岐ごとの手順、長い基準
assets/ 出力にそのまま使うファイル 読まずに、コピー・加工する テンプレート、雛形、ひな形コード

守ること。

  • 参照は 1 段にする。 SKILL.md から参照ファイルへ。参照ファイルから別の参照ファイルへ、と入れ子にしない(部分的にしか読まれず、抜けが出る)
  • 長い参照ファイルは、先頭に目次を置く。
  • スクリプトは、失敗を握りつぶさない。 エラーは明示し、対処の仕方を出力する。agent に推測で続行させない
  • スクリプトは、実際に実行して確かめる。 書いただけのスクリプトは、動くか分からない
  • 同じ情報を、SKILL.md と参照の両方に書かない。 詳しいほうを参照に置く

ステップ 7:検証する

  1. 構造チェック。 name、description、行数、参照のリンク切れ、入れ子を機械で確かめる(7.1 の skill_lint.py)
  2. 評価を実行する。 新しいセッションで、評価の表を 1 行ずつ実行し、結果を記録する。skill 有りと無しの両方で走らせて、差を見る
  3. 複数のモデルで試す。 使う予定のモデルすべてで、同じ評価を実行します。小さなモデルでは、手順が足りているかを、大きなモデルでは、説明しすぎていないかを確かめます
  4. トランスクリプトを読む。 結果だけでなく、agent がどう動いたかを見ます(想定外の探索経路、読まれなかった参照、無視された指示)。ここに、書き直しの手がかりがあります
  5. コストを記録する。 トークンと所要時間。skill 有りで成功率が上がらず、コストだけ増えた場合は、削る(前回記事の論文の教訓)

Claude A/Claude B の方法(Anthropic)。 skill を書く側の agent(A)と、skill を使う側の別セッション(B)を分けます。B の動きを見て、A に「ここで迷った」「この指示は無視された」と戻し、A が skill を直します。同じ会話の中で、書いて、試して、満足しないことが、最も起きやすい失敗です。

ステップ 8:出荷して保守する

  • 置き場所。 リポジトリの skill ディレクトリ(ツールごとの場所は 2.5)。個人用は、ユーザーのホーム側
  • 変更は PR で。 skill はコードと同じです。人がレビューし、CODEOWNERS で担当を決めます。スクリプトを含む skill は、特に慎重に見ます(4.5)
  • 履歴は git に任せる。 skill の中に、更新履歴やバージョン表を書かない
  • 失敗駆動で更新する。 失敗が再発したら、skill の文言を直す前に、上の層で止められないかを問う(梯子)
  • 四半期に一度、削除テストをかける。 「消しても評価が通る行」を削る。評価が通らなくなったら、評価を見直す
  • 重複を許さない。 AGENTS.md や別の skill と、同じことを言っていないかを確かめる

3.4 よくある失敗と直し方

# 症状(検出できる形) 原因 直し方
1 発動しない、または誤って発動する description が曖昧、狭すぎる、広すぎる 「何を+いつ+境界」の型で書き直し、発動の評価で確かめる
2 本文を読まずに、description の要約どおりに動く description に手順を書いた description は「いつ」だけ。手順は本文へ
3 「いつ使うか」が本文にある 発動後に読まれるので、遅い description へ移す
4 背景、来歴、バージョン表、口調の指示がある 人間向けの書き方 削除する(削除テスト)
5 SKILL.md が長い(500 行超) 参照に出していない 分岐ごとに references へ
6 参照が入れ子になっている 構造が深い 1 段にする
7 何でも屋で、description が広い 責務が混ざっている 単一責任に分割する
8 AGENTS.md と skill に同じ内容がある 重複 1 か所にする(手順は skill、不変条件は AGENTS.md)
9 形式・長さ・順序が、毎回ぶれる 脆い操作を文章で頼んでいる スクリプトにする
10 出力が穴埋めのように硬い 創造的な作業を細かく縛っている 構造と比率だけを指定する
11 効いているか分からない 評価が無い 評価を作り、skill 有り/無しで比べる
12 スクリプトが失敗しても、agent が進む エラーを握りつぶしている 明示のエラーと、対処の出力
13 禁止の列挙で、むしろ禁止された行動が出る 禁止形が前面化している 肯定形に直し、最終防衛線だけ禁止形で。取るべき行動を添える
14 古くなった記述が残る(日付や版に依存) 時間依存の情報 「旧方式」の節に分け、現行だけを本文に
15 副作用のある手順が、勝手に動く 自動呼び出しが有効 人だけが呼べるようにする
16 他人の skill を、中身を見ずに導入した 供給網のリスク 4.5 のチェックリストで確認

3.5 作成チェックリスト

  • 作る前に、機械で止められないか(L1〜L3)を確認した
  • skill 無しで、実際に失敗する実例を 3 件集めた
  • 契約メモ(トリガー、完了基準、副作用、人に返す条件)を書いた
  • 評価(発動・振る舞い・圧力)を先に作り、skill 無しで失敗する(Red)ことを確認した
  • description は三人称で、「何を+いつ+境界」を書き、手順を書いていない
  • SKILL.md は短く(500 行未満)、ステップごとに検査できる完了基準がある
  • 参照は 1 段で、長い参照には目次がある。同じ内容を 2 か所に書いていない
  • 脆い操作はスクリプトにし、実際に実行して確かめた
  • 副作用がある skill は、人だけが呼べるようにした
  • 複数のモデルで、新しいセッションから評価を実行し、トランスクリプトを読んだ
  • skill 有り/無しで、成功率とコストを比べた
  • PR でレビューされ、担当(CODEOWNERS)が決まっている
  • 更新の条件(失敗の再発)と、四半期の削除テストを決めた

4. 使い方:導入・配置・呼び出し・確認・チーム運用

この章は、他人が作った skill、または自分たちで作った skill を、実際に使い始めるまでの手順です。流れは 5 つです。

4.1 入手:4 つの経路

経路 手順 向いている場面 注意
A. リポジトリにコピー skill のフォルダを .agents/skills/ に置いてコミットする チームの標準 skill。 この記事の 5 つもこの形 正本を 1 つにする。Claude Code 向けの同期は 4.2
B. gh skill(GitHub CLI 2.90.0 以降、public preview) gh skill preview OWNER/REPO で中身を確認 → gh skill install OWNER/REPO [skill[@version]] --agent <ホスト> --scope project --pin GitHub 上の公開 skill を、バージョン固定・来歴つきで入れる 公式の警告:skill は GitHub が検証していない。必ず先に preview する。--pin で固定し、更新は差分を見てから
C. skills CLI npx skills add owner/repo [--skill 名] [-a 対象ツール]、一覧は --list 複数ツールに、編集可能なファイルとしてコピーしたいとき 手動更新。plugin と両方入れると、skill が二重になる(どちらか一方)
D. plugin/マーケットプレイス 例:claude plugin install <plugin>@<marketplace>、codex plugin marketplace add <owner/repo>、copilot plugin marketplace add <owner/repo>、VS Code は「Chat: Install Plugin From Source」 自動更新したい、組織で配布したい 更新が自動なので、内容が変わる前提で固定と差分レビューの方針を決める

どれを選ぶか。 チームで育てる skill は A(レビューされ、バージョン管理される)。他人の skill は、まず B か C で読み、必要な部分を A に取り込んで編集するのが安全です。D は、自分たちで配布する側に回るときに使います。

4.2 配置:正本は .agents/skills/、Claude Code へは同期する

2.5 のとおり、多くのツールが .agents/skills/ を読み、Claude Code だけが .claude/skills/ を読みます。 正本を .agents/skills/ に置き、Claude Code 向けに同期します。

方法 内容 注意
シンボリックリンク .claude/skills を .agents/skills へのリンクにする Windows では、開発者モードか権限が要る
コピー(推奨) スクリプトで .agents/skills/ を .claude/skills/ に複製し、CI で差分を検査する 権限が要らず、どの OS でも動く
plugin skill を plugin にして配布する 配布の仕組みが要る

コピーの例です(標準ライブラリのみ。--check は CI 用で、ずれがあれば失敗します)。

scripts/sync_skills.py
#!/usr/bin/env python3
"""Keep .claude/skills in sync with the source of truth .agents/skills.

Usage (from the repo root): python scripts/sync_skills.py [--check]
"""
import filecmp
import shutil
import sys
from pathlib import Path

SRC, DST = Path(".agents/skills"), Path(".claude/skills")


def skill_names(root):
    return sorted(p.name for p in root.iterdir() if (p / "SKILL.md").is_file()) if root.is_dir() else []


def files(folder):
    return {p.relative_to(folder).as_posix(): p for p in folder.rglob("*") if p.is_file()} if folder.is_dir() else {}


def main(argv):
    check = "--check" in argv
    drift = []
    for name in skill_names(SRC):
        s, d = files(SRC / name), files(DST / name)
        drift += [f"{name}: missing {k}" for k in s if k not in d]
        drift += [f"{name}: differs {k}" for k in s if k in d and not filecmp.cmp(s[k], d[k], shallow=False)]
        drift += [f"{name}: extra {k}" for k in d if k not in s]
        if not check:
            shutil.rmtree(DST / name, ignore_errors=True)
            shutil.copytree(SRC / name, DST / name)
    if check:
        print("\n".join(drift) or "in sync")
        return 1 if drift else 0
    print(f"synced {len(skill_names(SRC))} skill(s)")
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

個人用の skill。 全プロジェクトで使うものは、個人の場所(~/.agents/skills/、Claude Code は ~/.claude/skills/)に置きます。チーム全員に効かせたいものを個人の場所に置くと、他の人に届きません。逆に、個人の好みをプロジェクトの .agents/skills/ に入れると、全員に配布されます(前回記事 第1章の「個人用とチーム用を分ける」と同じです)。

4.3 呼び出し:明示・自動・連鎖

呼び方 例 いつ使うか
明示 Claude Code・Copilot:/code-review。Codex:$code-review(/skills でも選べる)。Windsurf:@code-review skill が確実に動いてほしいとき。評価のとき。副作用のある skill
自動 依頼の内容が description に合うと、モデルが選ぶ 日常。AGENTS.md の導線(「バグ → bug-investigation」)も、この経路で skill に届く
連鎖 人が呼ぶ skill(ワークフロー)が、自動で選ばれる skill(規律)を順に呼ぶ 専用のワークフロー(第9章)。人が呼ぶ skill は、他の人が呼ぶ skill を呼ばない(依存を絡ませない)

注意。

  • Claude Code では、/name を文の途中に書くと、使う許可を与えるだけで、その場では実行されません。メッセージの先頭に書くと、直接実行されます
  • 単純な 1 ステップの作業では、agent は skill を読まないことがあります。 それは不具合ではなく、設計どおりです。複数ステップの作業で試してください
  • 引数は、ツールによって渡し方が違います(Claude Code では $ARGUMENTS、VS Code では /skill-name 追加の文脈)。引数に依存する skill は、移植性が下がります

4.4 確認:読み込まれたか、守られたか

読み込まれたか。

ツール 一覧の見方
Claude Code /skills(メニュー)、または「使える skill は?」と聞く
GitHub Copilot CLI /skills list、/skills info 名前。ターミナルからは copilot skill list
Codex /skills
Gemini CLI /skills list
共通 トランスクリプトに、skill の読み込みが出ているかを見る(表示はツールによって違う)

守られたか。 「読み込まれた」ことと「手順どおりに動いた」ことは別です。第3章のステップ 7 のとおり、結果だけでなく、トランスクリプトを読み、想定外の探索経路、読まれなかった参照、無視された指示を見ます。

動かないときは、2.6 の表に戻ります。 とくに、名前とディレクトリ名の不一致と、YAML の 1 行目の --- が、静かに失敗する典型です(skill_lint.py で防げます)。

4.5 チーム運用:skill は、コードと同じに扱う

項目 やること
レビュー skill の変更は PR にして、人がレビューする。指示ファイルの変更は、機能変更と別の PR にする(前回記事 第6章。skill は agent の行動を直接変える入力)
担当 CODEOWNERS に /.agents/skills/ を追加する。スクリプトを含む skill は、セキュリティの担当も入れる
構造チェックを CI に skill_lint.py、同期の --check、不可視文字の検査(前回記事のスクリプトの対象に .agents/ を追加)
評価 評価(発動・振る舞い・圧力)を、skill と一緒に置く(evals/)。変更のたびに、新しいセッションで再実行する
更新 失敗が再発したら、skill の文言を直す前に、上の層で止められないか(梯子)を問う。直すなら、その失敗を評価に足してから直す
削除 四半期に一度、使われていない skill、評価が通る削除可能な行を削る。skill は少ないほど、残りが選ばれやすい(2.4)
予算 常時読み込まれる description の合計と、skill の数に上限を置く。増やすときは、1 つ削る

CI の例です。

.github/workflows/skills-guard.yml
name: skills-guard
on: [pull_request]
permissions:
  contents: read
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4   # 本番ではコミット SHA で固定する
      - run: python .agents/skills/writing-for-agents/scripts/skill_lint.py .agents/skills
      - run: python scripts/sync_skills.py --check
      - run: python scripts/check_invisible_chars.py

4.6 安全:他人の skill は、他人のコードである

skill は、agent の行動を直接書き換える入力であり、スクリプトを実行できるものです。第三者の skill を入れることは、第三者のコードと、第三者の指示を、自分の権限で動かすことです。

実在するリスクです。

調査 結果
「Agent Skills in the Wild」(arXiv 2601.10338) 公開された skill 31,132 件のうち 26.1% に、少なくとも 1 つの脆弱性のパターン(データ流出 13.3%、権限昇格 11.8%)。5.2% は悪意が強く疑われる高重大度。スクリプトを含む skill は、脆弱である確率が 2.12 倍
Snyk「ToxicSkills」(2026-02-05。ベンダーのデータ) ClawHub と skills.sh の 3,984 件のうち、13.4%(534 件)に重大な問題。どの重大度でも 36.82%(1,467 件)に何らかの欠陥。人が確認した悪意のあるペイロードが 76 件で、その 91% はプロンプトインジェクションも併用していた。ClawHub に公開するのに必要なのは、SKILL.md と、作って 1 週間以上の GitHub アカウントだけ
後続の研究(arXiv 2610.33489、2610.32155、2610.19264) ClawHub の 66,157 件のうち 627 件が悪意あり(検出器の precision 80.2%、recall 95.2%)。単体では安全と判定された skill の組み合わせが、危険な連鎖になる例が 13.7%。6,309 件の監査では、約半数がシェルを実行でき、31% が外部へ送信でき、13% が認証情報に触れる。権限を宣言していたのは 6,061 件中 770 件で、その 59% は過小申告

ここから言えること。 ①公開レジストリは、中身を審査していません。②スクリプトが付いた skill は、特に危険です。③検査ツールは補助で、読む作業の代わりにはなりません(精度は約 80%、単体の検査は組み合わせのリスクを見逃す)。

各社の公式な注意。

  • Anthropic: plugin は「ユーザーの権限で、任意のコードを実行できる」。フック、MCP・LSP サーバーはサンドボックスの外で動く。自動更新は、レビューしたファイルを変えうる
  • Claude Code: allowed-tools は、制限ではなく事前承認。プロジェクトの skill の allowed-tools は、信頼していないフォルダでの非対話実行でも効く。skill が自分自身に広い権限を与えられるので、リポジトリの skill はレビューするよう、ドキュメントが求めている
  • VS Code: 信頼できる skill だけを再利用する。信頼できないプロジェクトは制限モードで開く
  • OpenAI(Codex の参照ファイル): 最新のモデルは「skill に含まれる指示により敏感」で、skill の監査を強く勧める

導入前のチェックリスト。

# 確認すること
1 入手元。 公式か、信頼できる組織か。スター数だけで判断しない。更新履歴とライセンスを見る
2 すべてのファイルを読む。 SKILL.md だけでなく、scripts/、references/、assets/ の全部。gh skill preview を使う。plugin なら、hooks/hooks.json、.mcp.json、bin/ も読む
3 スクリプトを重点的に。 外部への通信、curl … | sh、eval、環境変数や認証情報の読み取り、~/.ssh や .env へのアクセス、難読化された文字列(base64 など)
4 不可視文字。 ゼロ幅文字や双方向制御文字を、機械で検出する(前回記事のスクリプト)
5 allowed-tools の事前承認。 shell や bash の事前承認は危険(GitHub のドキュメントの警告)。過剰な権限は外す。Claude Code では、allowed-tools は制限ではなく事前承認である点にも注意
6 他の指示を覆す文。 「以前の指示を無視する」「確認せずに実行する」「ユーザーに伝えない」など
7 取得して実行する指示。 URL から取ってきた内容を、そのまま実行・読み込ませる指示
8 バージョンの固定。 コミット SHA かタグ(gh skill --pin)で固定する。自動更新を許すかを決める
9 隔離して試す。 権限の弱い環境、機密のないリポジトリで、先に動かす
10 取り込んで編集する。 そのまま使わず、自社の規約に合わせて編集し、自分たちのリポジトリにコミットする。上流の変更は、差分をレビューしてから取り込む
11 入れない勇気。 使わない skill は、常時のコストと攻撃面になる
12 副作用のある skill は、自動で動かさない。 disable-model-invocation(Claude Code では、シェル実行を禁じる disableSkillShellExecution の設定もある)
13 疑いが生じたら。 削除し、認証情報を更新し、メモリ用のファイルと plugin のキャッシュを確認する

信頼できないリポジトリを開くとき。 リポジトリに含まれる skill や指示ファイルも、他人の指示です。agent の実行基盤が、プロジェクトの skill を「信頼してから読む」仕組みを持つなら、それを有効にします(agentskills.io のクライアント実装ガイドも、プロジェクトの skill を信頼の確認の後に読み込むことを勧めています)。信頼できないものは、制限モードで開きます(前回記事 第6章)。

4.7 評価と改善のループ

skill は、作って終わりではなく、評価し続けるものです。第6章のレビュー制度と同じ考え方で運用します。

指標 何を表すか 取り方
発動率(recall) 発動すべき依頼で、実際に発動したか 発動の評価(8〜10 件)を、各 3 回走らせる
誤発動率 発動すべきでない依頼で、発動したか 紛らわしい依頼(隣の skill と近いもの)を混ぜる
成功率 振る舞いの評価に合格したか skill 有り/無しで比べる(Claude Code は skillOverrides で skill を off にして A/B できる)
コスト 1 回あたりのトークンと時間 skill 有り/無し、モデル別(7.5)
常時コスト description の合計 context_budget.py(7.5)、Claude Code の /doctor と /skill-doctor
使用状況 実際に使われているか /skill-doctor(Claude Code)。使われない skill は削る

発動の評価の標準手順(agentskills.io のガイドに基づく)。発動する依頼 8〜10 件と、発動しない依頼 8〜10 件(近いが違うものを含める)で、合計約 20 件を作ります。各依頼を 3 回ずつ走らせ、発動率が 0.5 以上なら「発動」と数えます。60% で description を直し、40% は検証用に取っておき、検証での合格率が最も高い版を選びます。5 回程度の反復で足りることが多い、とされています。

簡単な台帳。 skill ごとに、バージョン(git のタグ)、最後に評価した日、発動率、誤発動率、1 回あたりのトークン、担当者を、1 行で記録します。台帳が無い skill は、効いているかどうかが分かりません。


5. 実在の skill に学ぶ:世界で広く使われている公開リポジトリを読む

第3章の原則は、机上の理屈ではなく、公開されている skill から取りました。この章では、何を、どのリポジトリから、なぜ取り入れたかを示します。そのまま使うためではなく、自分たちの skill を作るときの、実物の見本として読んでください。

星の数とライセンスは 2026-11-18 に確認した値です。動くので、使う前に確認し直してください。星の数は人気の目安であって、品質や安全性の保証ではありません。他人の skill は、4.6 の点検を通してから入れます。

5.1 どのリポジトリを読むか

リポジトリ ★(2026-11) ライセンス 特徴 本記事が学んだこと
anthropics/skills 約 19.7 万 skill ごとの LICENSE.txt。確認した 8 件は Apache-2.0。リポジトリ全体のライセンスは無い 公式の例。文書(docx・pdf・pptx・xlsx)、ツール(skill-creator・webapp-testing・mcp-builder)、創作など 19 本 作り方の標準手順、評価と description の最適化、スクリプトの扱い
obra/superpowers 約 31.9 万 MIT 開発の工程全体を 15 本の skill にした。hook で起動時に注入する description は「いつ」だけ、skill の圧力テスト、鉄則と合理化表
mattpocock/skills 約 32.7 万 MIT 日常の開発(engineering・productivity)の skill 集。自分の .agents ディレクトリから 呼び出しの規則、質問の技法、引き継ぎ、writing-for-agents
openai/skills(非推奨) 約 2.9 万 skill ごと Codex 向けの skill 集。非推奨になり、plugin(openai/plugins)へ移行 形式(agents/openai.yaml)、skill-creator の考え方
github/awesome-copilot 約 4.1 万 MIT Copilot 向けの skill・agent・instructions・hook の大きな目録 規約の機械検査、否定の引き金の書き方
vercel-labs/agent-skills 約 3.4 万 MIT(README と frontmatter による) 70 の規則から生成した AGENTS.md、最新の指針をその場で取りに行く skill 単一の情報源から生成する、スクリプトを優先する

ライセンスの注意(anthropics/skills)。 README は、これらの skill が「デモと学習の目的で提供される」と述べています。ライセンスは skill ごとの LICENSE.txt で決まり、使う skill のものを読みます。2026-11-06 に、Office 系の skill が Apache 2.0 に移されました(それ以前の README は「ソース公開で、オープンソースではない」と説明していたので、古い解説は現状と食い違います)。

5.2 anthropics/skills:作り方の標準手順を、公式がどう書いたか

skill-creator:skill を作る skill

skills/skill-creator は、skill の作り方そのものを skill にしたものです(SKILL.md は約 485 行。「500 行未満が理想」と自分で述べています)。構成は agents/(採点・比較・分析の 3 役)、scripts/(評価の実行、ベンチマーク集計、description の最適化、検証、パッケージ化)、eval-viewer/、references/schemas.md です。定める手順は次のとおりです。

段階 skill-creator の手順 本記事(3.3)の対応
1 意図を捉える。 まず会話から拾い、足りなければ 4 つを聞く(何をできるようにするか/いつ起動するか/出力の形式/テストを用意するか) ステップ 1〜2(失敗の実例、契約メモ)
2 インタビューと調査(境界の事例、形式、成功基準、依存) ステップ 1〜2
3 SKILL.md を書く。description が「主要な起動の仕組み」で、「いつ使うか」はすべてここに書き、本文には書かない ステップ 4〜5(description、本文)
4 テストケースを 2〜3 件、evals/evals.json に書く(最初は assertions なし) ステップ 3。skill-creator は本文のあとに作るが、本記事は先に作る
5 実行。同じターンで、skill ありの実行と、基準(skill なし。改善なら旧版)の実行を起動する。total_tokens と duration_ms は、完了の通知でしか取れないので、すぐ timing.json に保存する ステップ 7
6 採点。grader が grading.json(text・passed・evidence)を出し、集計し、analyzer が「区別できない」「不安定」な assertion を指摘する ステップ 7
7 人のレビュー。ビューアで見て、feedback.json に書く。満足、フィードバックが空、改善が止まった、のどれかで終える ステップ 7〜8
8 description の最適化。 20 件のクエリ(起動すべき 8〜10、紛らわしい非起動 8〜10。パスや誤字などのノイズ入り)を、60% 訓練・40% 検証に分け、各 3 回、最大 5 反復。検証側の点数で選ぶ(過学習を避けるため) ステップ 4、7、4.7

そこから取れる教訓は 4 つです(いずれも skill-creator の本文より)。

  • モデルは、skill を「使わなすぎる」。 そのため description を、少し「押しの強い」書き方にする。自分でこなせる簡単な依頼では、skill は参照されないので、テストのクエリは簡単すぎてはいけない
  • 理由を説明する。 「大文字の MUST・ALWAYS・NEVER で押し通すのは、黄信号」。理由を書けば、モデルは例外も正しく扱える(3.2 原則 8)
  • 試験のたびに同じ作業が繰り返されているなら、スクリプトにする。 サブエージェントが毎回同じ補助コードを書き直しているなら、skill に同梱する
  • 参照ファイルが 300 行を超えたら、目次を付ける

5 つの skill に見る設計

skill 構成の特徴 学べること
webapp-testing(SKILL.md 約 96 行) scripts/with_server.py(サーバーの起動・停止を包む)、examples/ ①スクリプトはブラックボックスとして使う(「まず --help を実行し、必要なときだけソースを読む」)。②決定木(静的 HTML か動的アプリか)と、偵察してから動く手順。③networkidle を待つ、といった ❌/✅ の対
pdf(約 314 行) FORMS.md、REFERENCE.md、8 本のスクリプト ①押しの強い引き金(「PDF に関することなら何でも」)。②段階的開示(フォームは FORMS.md、上級は REFERENCE.md)。③落とし穴を本文に直接(上付き文字が黒い四角になる)。クイックリファレンス表
docx(約 92 行) scripts/office/(検証・変換)、テンプレート ①否定の範囲(「PDF・スプレッドシート・Google ドキュメントには使わない」)。②落とし穴だけを書く(「モデルは API を知っている。書くのは落とし穴」)。③結果を PDF と画像に描画して読む検証の手順
mcp-builder(約 252 行) reference/ に言語別の詳細、scripts/ に評価の道具 ①4 つの段階と「第 N 段階で X を読む」の導線。SKILL.md が地図になる。②最後の段階が評価(独立・読み取り専用・複雑・検証可能・安定、の 5 条件を満たす 10 問)。③SDK の版の分岐
frontend-design(約 71 行) SKILL.md とライセンスのみ ①役割の与え方(デザインスタジオのデザインリード)。②モデルの既定の癖に名前を付けて避ける(クリーム色の背景、テラコッタのアクセント、SaaS のカード)。③2 段階(計画を依頼に照らして確認 → 作る)

5.3 obra/superpowers:規律を skill にする

superpowers は、開発の工程(発想 → 計画 → 実装 → レビュー → 完了)を、15 本の skill にしたものです。skill の「中身」より、skill を信頼できるものにする方法から学べます。

description は「いつ」だけ書く

writing-skills は、description が「使うべき場面(引き金と症状)だけを書き、Use when… で始める」ことを求めます。skill の手順を要約してはいけません。要約を読んだ agent は、本文を読まずに要約のとおりに動くからです。 根拠となった実例が、references/discovery.md に書かれています。

  • description に「タスクの間にコードレビュー」と書いた skill で、agent はレビューを 1 回だけ行った。本文のフローチャートは 2 回を指示していた
  • description を「独立したタスクがある実装計画を実行するとき(Use when executing implementation plans with independent tasks)」に直すと、フローチャートのとおりに動いた
  • 悪い例:「TDD に使う。テストを先に書き、失敗を見て…」。良い例:「機能やバグ修正を実装するとき、実装コードを書く前に」

本記事の立場。 Anthropic と Agent Skills の仕様は「何をするか」と「いつ使うか」の両方を求めます。両者の折衷として、description は「何をするか」を1 句までにとどめ、主に「いつ使うか」と隣との境界を書きます。手順は書きません(3.2 原則 3、7.1)。

skill を、テストしてから出す(圧力テスト)

writing-skills の鉄則は「失敗するテストが先。それが無い skill は作らない」です。skill 自体にテスト駆動を適用します。

段階 やること
RED skill なしで、圧力のかかった場面を agent に走らせ、言い訳を逐語で記録する。3 つ以上の圧力(時間、手戻りの費用、疲れ、権威、など)を組み合わせ、A/B/C の選択を強いて、「実際に動かせる」場面にする
GREEN 観測した失敗だけに対処する、最小の skill を書く
REFACTOR 抜け道を、4 つの方法で塞ぐ。①明示的な否定、②合理化表の行、③red-flag の項目、④description への症状の語。最後に、「この skill は、別の書き方ができたか」を agent に聞く

TDD の skill は、6 回の RED-GREEN-REFACTORを経て、10 を超える固有の言い訳を洗い出したと記されています(2025-10-03)。純粋な参照の skill は、テストしません。 機械で縛れる制約は、skill にせず自動化します。そして重要なのが「形を、失敗に合わせる」という指針です。

失敗の種類 効く形
規則を飛ばす 禁止と、合理化表(言い訳 → 反論)と、鉄則
出力の形が違う 肯定の手順(「禁止は、形を整える問題では逆効果」)
要素が抜ける 必須のスロット(欄を埋めさせる)

これは、3.2 原則 8(肯定形と禁止の使い分け)の出どころの 1 つです。

3 つの規律の skill

skill 鉄則 特徴
test-driven-development 失敗するテストなしに、本番コードを書かない。先に書いたコードは「消す」 RED・GREEN・REFACTOR の各段階に必須の確認。11 行の合理化表。「Red Flags:止めて、やり直す」の一覧
systematic-debugging 根本原因の調査なしに、修正しない 4 つの段階(根本原因 → パターン → 仮説 → 実装)を、終えてから次へ。複数の構成要素にまたがるなら、境界ごとに計装する。1 つの仮説、1 つの変数。3 回以上の修正に失敗したら、「止まって、設計を疑う」
verification-before-completion 新しい検証の証拠なしに、完了を主張しない 5 段階のゲート(コマンドの特定 → 実行 → 出力を読む → 検証 → 主張)。「should」「たぶん」は赤旗。agent の「成功」の報告は証拠ではないので、VCS の差分を確認する

この 3 つは、本記事の bug-investigation(7.4)、TDD の規律(前回記事 第5章)、code-review の証拠の段階(6.4、E0〜E5)の源の 1 つです。requesting-code-review と receiving-code-review は、7.2 の独立レビューと、指摘を受ける側の手順(rereview.md の最後の節)に取り入れました。

注意:規則と実物の差、起動の押し込み

  • 自分の規則に、自分で従っているか。 writing-skills の目標(頻繁に読み込むものは約 200 語まで、など)は努力目標で、リポジトリ自身の skill のほうが大きい(writing-skills で約 16.7 KB)。だから本記事は、規則を skill_lint.py で機械的に確かめます(7.1)
  • 起動を hook で押し込む。 SessionStart の hook が using-superpowers を、起動・クリア・圧縮のたびに文脈へ注入し、「1% でも当てはまる可能性があるなら、skill を確認せよ」と求めます。確実に発動させる代わりに、常時の文脈を払います。 本記事は、AGENTS.md に導線の 1 行を置く方式にしました(前回記事、第2章)
  • リポジトリ自身の AGENTS.md が、skill の変更に、前後の敵対的な評価を求めています(評価の道具は別リポジトリにあり、筆者は未確認)

5.4 mattpocock/skills:日常の開発を、小さな skill の集合にする

本記事の writing-for-agents、specification(質問の技法)、bug-investigation(ループ優先)、code-review の考え方の多くは、このリポジトリに負っています。

領域 中身 本記事での使いどころ
skills/engineering(20 本) code-review、diagnosing-bugs、tdd、to-spec、to-tickets、codebase-design、domain-modeling、implement、pr、retro、triage など 7.2〜7.4、第9章
skills/productivity(7 本) grilling、handoff、writing-for-agents、teach など 7.1、7.3、7.5
misc・in-progress・deprecated 凍結した skill、出していない skill、非推奨 育て方の見本(下記 SCOPE)

学べる設計が 5 つあります。

  1. 呼び出しの規則(SKILL-MECHANICS.md)。モデル起動(既定。引き金の多い description を持ち、常に文脈を払って、発見されやすさを得る)とユーザー起動(disable-model-invocation: true。文脈のコストはゼロだが、「あなたが索引」という認知負荷を払う)を選ぶ。「agent が自分で到達する必要があるとき、または別の skill から呼ぶときだけ、モデル起動にする」。ユーザー起動の skill は、モデル起動の skill を呼べるが、別のユーザー起動の skill は呼べない。ルーターの skill(他を名指しする 1 つの skill)は、ほのめかすだけで、起動はできない(2.7、7.1)
  2. 質問の技法(grilling)。決定の木と frontier を、ラウンドで聞く(7.3)
  3. 引き継ぎ(handoff、約 15 行)。OS の一時ディレクトリに書き、既存の成果物は複製せずパスで参照し、秘密を伏せる(7.5 の引き継ぎメモ)
  4. 検査を先に作る。 retro は「規則を書くより、検査を作ることを既定にする」と述べる(6.10 の是正の梯子)。codebase-design は「アダプターが 1 つなら、仮の継ぎ目。2 つなら、本物の継ぎ目」(7.3 のテストの境界)。pr は「要約・証拠・マージの危険」の 3 部構成(6.8 のパケット)
  5. 育て方の規律(SCOPE.md)。提案は、「観測された失敗」と「方針に合う」の両方を示せるものだけが開いたままになり、新しい skill の提案は受け付けていない。リポジトリ自身の CLAUDE.md は、昇格させる skill に 4 節の説明ページを求め、サブエージェントを呼ぶ skill は新しい文脈で始めるよう求める(原則 9「評価で育てる」の運用)

5.5 そのほか:目録、規約の検査、生成、導入の道具

対象 学べること
openai/skills(非推奨) 冒頭に「このリポジトリは非推奨」とあり、openai/plugins へ移行。skills/.system/skill-creator は「コンテキストウィンドウは公共財」と述べ、「入れてはいけないもの」(README、CHANGELOG など)を列挙。形式は SKILL.md + agents/openai.yaml(interface: の 5 つのキーと、policy.allow_implicit_invocation)。plugin は .codex-plugin/plugin.json に skills・.mcp.json・hooks.json を同梱し、.agents/plugins/marketplace.json で配る
github/awesome-copilot 規約:name は小文字とハイフンで 64 文字以内、フォルダ名と一致、description は 10〜1024 文字、資産は 5 MB 未満。skill:validate で機械検査し、外部の plugin は vally lint とインストールのスモークテストに通す。否定の引き金の例:「日常の機能実装には起動しない」(acquire-codebase-knowledge)
vercel-labs/agent-skills 「SKILL.md は 500 行未満」「スクリプトを優先する。実行は文脈を消費しない(出力だけが消費する)」「参照は 1 段」「進捗は stderr、JSON は stdout」。react-best-practices は、70 の規則(各々に「悪い例/良い例」の対)から、108 KB の AGENTS.md をビルドで生成し、評価用のテストケースも生成する(件数が SKILL.md の 70 と README の「40+」でずれているのは、手で書いた数を生成物に残す危険の実例)。web-design-guidelines は、最新の指針をレビューのたびに取りに行く(埋め込まない)
導入の道具 npx skills add owner/repo(Node 22.20 以降。既定は正本へのシンボリックリンク、--copy でコピー。skills-lock.json に SHA-256 を記録。テレメトリが既定で有効で、DISABLE_TELEMETRY=1 で止める)、gh skill install(GitHub CLI 2.90 以降。来歴を frontmatter に書き込む)、skills.sh(インストールの匿名統計で並べた目録)。詳細は 4.1

5.6 横断パターン:良い skill が共有すること

共通点 実例
**description が「いつ」を書き、**ユーザーの言葉で、テストされている skill-creator の 20 件のクエリ、近い非起動の事例、検証側の分割(4.7)
**SKILL.md は地図。**詳細は必要になってから読む mcp-builder の段階ごとの導線、pdf の FORMS/REFERENCE、vercel の rules/
スクリプトはブラックボックス(--help、stdout に JSON、stderr に進捗) webapp-testing の with_server.py
モデルに無いものだけを書く docx の落とし穴だけ、mattpocock の「すでに守っている指示の剪定」
観測された失敗から書く Anthropic の with/without 実行、superpowers の RED、mattpocock の「Observed failure」
検証を skill に組み込む docx の描画して読む、mcp-builder の評価問題、superpowers の完了ゲート
単一の情報源から、索引と生成物を作る vercel の AGENTS.md、awesome-copilot の README とマーケットプレイス
名前による合成と、起動の制御 ユーザー起動とモデル起動(mattpocock)
形を失敗に合わせる 規則破りには鉄則と表、形の問題には肯定の手順(superpowers)

弱い skill が犯す誤りは、ほぼ逆です。description が手順の要約か、曖昧。肯定形で書けることを、大文字の禁止で押し通す。引き金をテストしない。README や CHANGELOG が skill の中に混ざる。件数のような、手で書いた数が古くなる。

流派は割れています。 本記事は、次のように立場を取りました。

論点 一方 もう一方 本記事の立場
description に書くこと 「何をするか」と「いつ使うか」(Anthropic、OpenAI、仕様) 「いつ使うか」だけ(superpowers) 「何を」は 1 句まで。主は「いつ」と境界。手順は書かない
起動の強さ 少し押しを強く(Anthropic。使わなすぎを防ぐ) 否定の引き金を足す(awesome-copilot)、ユーザー起動では引き金を削る(mattpocock) 押しを強く、かつ「Not for」で境界を引く。紛らわしい非起動の事例で評価する
文体 理由を説明する(Anthropic、mattpocock) 鉄則と合理化表(superpowers) 失敗の種類で使い分ける(3.2 原則 8)
作る順序 書いてから評価する 先に失敗を観測する(RED) 先に失敗を観測する(3.3 ステップ 1、3)

この章から持ち帰ること。 ①公開の skill は、見本として読み、4.6 の点検を通して、必要な部分を自分のリポジトリに取り込む。②規則(行数、description)は、機械で確かめる。③skill は、観測された失敗から書き、評価してから出す。④流派の違いは、失敗の種類と、コストの払い方で選ぶ。


次は Part 2

Part 2 では、レビューという仕事を、人・agent・機械にどう分けるか(第6章)を決めてから、そのまま使える 5 つの汎用 skill の全文(第7章)を作り、続けるための運用(第8章)までを扱います。


参考リンク

本文の主張は、以下の一次資料と、公開リポジトリのソースで確認しました(2026-11 時点)。一部の文書は、保存版(Web Archive)や公開ミラーで内容を確認しています。リンク先は更新されることがあります。数値は、測定した主体(ベンダー、論文、第三者)が出したものです。

Agent Skills の標準と、各ツールの文書

公開されている skill・agent のリポジトリ

skill の効果と安全性

前回の記事

0
0
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
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?