前回の記事では、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月時点で、公式ドキュメント、公式リポジトリのソース、論文で確認した内容です。モデル名、各ツールのパスと上限、道具の評価は変わりやすいので、使うときに最新の文書を確認してください。数値は、測定した主体(ベンダー、論文、第三者)が出したもので、都度そう書きます。他社の数字は、自分たちの目標にしません。
先に結論
- 役割を分ける。 AGENTS.md は常に効く最小の契約。skill は、作業ごとに必要なときだけ読み込まれる手順。subagent は別の文脈・権限・モデルの役。hook・CI・テストは、例外を許さない柵。判断と責任は、人が持つ
- skill の効き目は、description がほぼ決める。 起動時に読まれるのは名前と description だけ。「いつ使うか」と境界だけを書き、手順は書かない
- 作る前に、梯子を上る。 構造 → lint・型 → テスト・hook → 文章の順に、止められないか確かめる。skill は最後の手段。作るなら、失敗を先に観測し、評価を先に作る
- 他人の skill は、実行コードとして扱う。 読み、固定し、点検する
- チームのレビューは、責任分担から設計する。 人は、作るべきか・危険なコード・前例・証拠の検証・責任を持つ。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。アブストラクトの水準での確認です)。
読み方と注意。 評価は端末・コンテナのタスクに限られ、長さを揃えた対照が無いため、「文脈が増えたこと自体」の効果も混じります。それでも、方向は一貫しています。
- 実際の専門性から作った skill は効く。agent に一から書かせた skill は効かない。 agentskills.io のガイドも、実際のタスクや runbook から作り、LLM に何もないところから作らせないよう求めています
- 少なく、焦点を絞る。 3 つ以内の焦点のある skill が、包括的な束に勝ちました
- 短く、適度に。 包括的すぎる skill は、効果がほぼ消えます
- 効いているかは、測る。
この記事の設計は、この 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 つの帰結が出ます。
- skill は、少なく、鋭く。 数が増えるほど、個々の description が削られ、選ばれにくくなります
- 本文の大事な指示は、先頭に置く。 長い会話のあと、圧縮で本文が切られる場合があります(Claude Code では先頭 5,000 トークンまで)。長い手順は、参照に出します
- 決定論的な処理はスクリプトに。 実行するだけなら、中身は文脈に入らず、コストがほぼゼロです
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 を読むかは未確認 |
共通の置き方(推奨)。
-
正本は
.agents/skills/に置く。 Copilot、Codex、Cursor、Gemini CLI、OpenCode、Amp、Cline、Warp が、プロジェクト単位でこの場所を共有しています -
Claude Code 向けに
.claude/skills/へ同期する。 方法は 3 つです。①シンボリックリンク(Windows では、開発者モードか権限が要る)、②スクリプトか CI でコピー、③plugin として配布。Windows のロックされた環境では、②が確実です - 拡張フィールドは、使うツールが決まってから足す。 仕様のフィールドだけなら、どのツールでも同じに動く
-
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 通りです。
-
agent に skill を載せる。 Claude Code の subagent の
skills:(全文を事前に読み込む)、VS Code の custom agent のskills -
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:検証する
-
構造チェック。 name、description、行数、参照のリンク切れ、入れ子を機械で確かめる(7.1 の
skill_lint.py) - 評価を実行する。 新しいセッションで、評価の表を 1 行ずつ実行し、結果を記録する。skill 有りと無しの両方で走らせて、差を見る
- 複数のモデルで試す。 使う予定のモデルすべてで、同じ評価を実行します。小さなモデルでは、手順が足りているかを、大きなモデルでは、説明しすぎていないかを確かめます
- トランスクリプトを読む。 結果だけでなく、agent がどう動いたかを見ます(想定外の探索経路、読まれなかった参照、無視された指示)。ここに、書き直しの手がかりがあります
- コストを記録する。 トークンと所要時間。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 用で、ずれがあれば失敗します)。
#!/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 の例です。
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 つあります。
-
呼び出しの規則(
SKILL-MECHANICS.md)。モデル起動(既定。引き金の多い description を持ち、常に文脈を払って、発見されやすさを得る)とユーザー起動(disable-model-invocation: true。文脈のコストはゼロだが、「あなたが索引」という認知負荷を払う)を選ぶ。「agent が自分で到達する必要があるとき、または別の skill から呼ぶときだけ、モデル起動にする」。ユーザー起動の skill は、モデル起動の skill を呼べるが、別のユーザー起動の skill は呼べない。ルーターの skill(他を名指しする 1 つの skill)は、ほのめかすだけで、起動はできない(2.7、7.1) -
質問の技法(
grilling)。決定の木と frontier を、ラウンドで聞く(7.3) -
引き継ぎ(
handoff、約 15 行)。OS の一時ディレクトリに書き、既存の成果物は複製せずパスで参照し、秘密を伏せる(7.5 の引き継ぎメモ) -
検査を先に作る。
retroは「規則を書くより、検査を作ることを既定にする」と述べる(6.10 の是正の梯子)。codebase-designは「アダプターが 1 つなら、仮の継ぎ目。2 つなら、本物の継ぎ目」(7.3 のテストの境界)。prは「要約・証拠・マージの危険」の 3 部構成(6.8 のパケット) -
育て方の規律(
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 の標準と、各ツールの文書
- Agent Skills specification
- agentskills/agentskills、Governance(2026-11-04 採択)
- Best practices for skill creators、Optimizing skill descriptions、Evaluating skill output quality、Using scripts in skills、How to add skills support to your agent
- Anthropic: Introducing Agent Skills、Equipping agents for the real world with Agent Skills
- Claude Platform: Agent Skills overview、Skill authoring best practices
- Claude Code: Skills、Subagents、Hooks guide、Manage costs effectively、Extend Claude Code、Code Review、Customize Code Review(REVIEW.md)
- GitHub Copilot・VS Code: Agent skills(GitHub Docs)、Use Agent Skills in VS Code、Custom agent file reference、Custom agents configuration、Hooks for GitHub Copilot
- GitHub CLI:
gh skillマニュアル、Changelog 2026-04-16: Manage agent skills with GitHub CLI、Changelog 2025-12-18: Copilot now supports Agent Skills - OpenAI Codex: Agent Skills、Cursor: Agent Skills、Gemini CLI: Agent Skills、Gemini CLI: Subagents、OpenCode: Skills
- AGENTS.md(agentsmd/agents.md)
公開されている skill・agent のリポジトリ
- anthropics/skills(skill-creator)
- obra/superpowers(writing-skills、requesting-code-review、receiving-code-review、verification-before-completion)
- mattpocock/skills(writing-for-agents、SKILL-MECHANICS.md、grilling)
- openai/skills(非推奨)、openai/plugins
- github/awesome-copilot
-
vercel-labs/agent-skills、vercel-labs/skills(
npx skills) - addyosmani/agent-skills
- ciembor/agent-rules-books
skill の効果と安全性
- SkillsBench: Benchmarking How Well Agent Skills Work Across Diverse Tasks(arXiv 2602.12670)
- More Skills, Worse Agents? Skill Shadowing Degrades Performance When Expanding Skill Libraries(arXiv 2605.24050)
- Agent Skills in the Wild(arXiv 2601.10338)
- From Instructions to Exploits(arXiv 2610.33489)、Detecting Insecure Compositions of Clean Agent Skills(arXiv 2610.32155)、Beyond Maliciousness(arXiv 2610.19264)
- Snyk: ToxicSkills