# Agent Skills実践ガイド：開発効率を最大化するスキル作成術 - **URL**: https://danicat.dev/ja/posts/the-pragmatic-guide-to-agent-skills/ - **Author**: ダニエラ・ペトルザレク - **Date**: 2026-08-29 - **Categories**: Agentic Coding - **Summary**: コーディングエージェント向けカスタムAgent Skillsの実践ガイド：ドキュメント更新、プロセス自動化、エージェント特性における具体的な活用法を詳しく解説。 --- 信じられないかもしれませんが、[**Agent Skills**](https://agentskills.io)標準が誕生してからまだ1年も経っていません。[Anthropicによる最初のブログ記事](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)が公開されたのは2025年10月のことで、当初はClaude Codeの拡張機能として導入され、同年12月に正式なオープン標準となりました。この仕様は極めて実用的であったため、瞬く間に主要なコーディングエージェントやエージェント開発フレームワークに採用され、AIモデルにモジュール化された指示、決定論的なスクリプト、専門的なドメインワークフローを装備するためのデファクトスタンダードとなりました。 そして現在、多くの開発者がスキルやプログレッシブ・ディスクロージャー（段階的開示）モデルの利点を知るようになりました。しかし、私たちはスキルを真に効果的に活用し、自ら作成できているでしょうか？ この記事では、スキルの発見や出所（来歴）の管理から、開発と最適化に至るまで、Agent Skillsを扱う上での主要な課題と実践的なアプローチを探っていきます。 本文中で紹介するすべてのスキルとサンプルは、Antigravity CLIおよびGemini 3.7 Flashを使用して検証していますが、他のエージェント基盤（ハーネス）やモデルをお使いの方もぜひ試してみてください。それでは、Agent Skillsの世界へ飛び込んでみましょう！ ## スキルを作るべきか、既存のスキルを使うべきか ソフトウェアエンジニアが常に直面するジレンマ：「自分で作るべきか、それとも既存のものを調達すべきか？」 この問いにはさまざまなアプローチがありますが、私のプラグマティック（実践的）な判断基準を共有します： ```goat +-----------------------------------------+ | Is this process specific to your repo | | or codebase? | +-----------------------------------------+ | | Yes | | No | v | +-----------------------+ | | Do you know a skill |<-------------------+ | | that does the job? | | | +-----------------------+ | | | | | | Yes | | No | | v v | | +--------------------+ +------------------+ | | | Passes security & | | Spent too much | | | | integrity checks? | | time looking? | | | +--------------------+ +------------------+ | | | | | | | | Yes | No | Yes | No | | | | | | v | | | | | +---------------+ | | | | | | Search for | | | | | | | a skill | | | | | | +---------------+ | | | | | | | | | v v +------------+ | | +------------------+ | | | Build your own | +--------------------->| skill | | +------------------+ | | v v +-----------------------------------+ | Profit! | +-----------------------------------+ ``` 多少入り組んだフローチャートに見えるかもしれませんが、要点は明快です：信頼できる正式なソースがあるか、攻撃ベクトルに晒されていないという絶対的な確信がない限り、**自前で作るほうが良い**ということです。 スキル作成にかかる労力は非常に小さいため、自作をお勧めしない状況はほとんどありません。唯一の例外は、スキルの品質を判断するためのドメイン知識が不足している場合です。その場合、誤った挙動のエコーチェンバー（悪循環）を生み出してしまうリスクがあるため注意が必要です。 十分な知識があるなら、自前のスキル作成はコーディングエージェントによる開発者生産性を飛躍させる究極のハックとなります。だからこそ、すべての本格的なエンジニアは「スキルを作るスキル」をマスターすべきだと私は確信しています（言葉遊びのようですが）。 ## 「スキルを作るスキル」を極める 役立つスキルを作るための秘訣は、エージェントの行動パターンを観察することに尽きます。たった1回のコーディングセッションですぐに完璧なスキルを思いつくのは難しいかもしれませんが、エージェントを使い込み、その挙動を観察すればするほど、カスタムスキルで埋めるべき知識や振る舞いのギャップが見えてきます。 具体的な例を見ればより分かりやすいでしょう。まずは、私たちが作成できるスキルの種類（レベル分類）を見ていきましょう： ### レベル1：ドキュメント（Documentation） 特定の技術やライブラリについて解説し、モデルの内蔵知識を補強または上書きするスキルです。例えば、学習データに含まれる古い情報が原因で、モデルが非推奨のライブラリや古いSDK、陳腐化したコーディングパターンを提案してくることは日常茶飯事です。スキルを使ってソフトウェアに関するモデルの知識を最新化することは、この技術の最も基本的かつ効果的な使い道です。 ドキュメントスキルの典型的な構成は、最新のナレッジ、コマンドライン、コードスニペット、外部URLをまとめた単一の`SKILL.md`ファイルです。扱う領域が複雑な場合は、`SKILL.md`を参照ファイルやアセットファイルに分割することで、プログレッシブ・ディスクロージャーの利点を最大限に引き出すことができます。 エージェントが古いパターンや古いSDKバージョンを使っているのを見かけたとき、あるいは最適とは言えない実装を繰り返し生成するときに、このタイプのスキルを作成してください。多くのベンダーが提供するスキルもこのカテゴリに属します。例えば、主要なGoogle製品向けのスキルを集めた[Google Skills](https://github.com/google/skills)リポジトリなどが代表例です。 私が作成したドキュメントスキルの例として、[ebitengineer](https://skills.danicat.dev/game-dev/ebitengineer/)があります。このスキルは、Ebitengineで2Dゲームを開発している際に、行列演算の順序の誤り、モジュール分割の不備、状態管理の欠如、本番用フォントではなくデバッグ用テキストの乱用など、繰り返し発生する問題に気づいたことをきっかけに作成したものです。 ### レベル2：プロセス（Process） [コードレビューの実施]({{< ref "/posts/20260303-code-reviews-in-2026" >}})、セキュリティ監査、パフォーマンス分析など、特定のプロセスやワークフローを厳密に実行させるスキルです。このタイプのスキルには、ドキュメント的な知識だけでなく、タスクを実行するためのカスタムスクリプトやCLIツールが同梱されるのが一般的です。これにより、毎回モデルにゼロからスクリプトを書かせる手間を省くことができます。 同じタスクを繰り返しエージェントに指示していることに気づいたとき、特にスクリプト化できる決定論的なステップが存在する場合は、プロセススキルを作成すべきです。私が多用しているプロセススキルとしては、ソーシャルメディア、Google Analytics、Google Search Consoleからデータを収集・分析する[analytics](https://skills.danicat.dev/analytics)スキルセットがあります。 オンラインでの存在感を最適化することは私の仕事の重要な一部ですが（誰にも見られないコンテンツを作っても意味がありません）、各プラットフォームのアナリティクス画面を1つずつ手作業で確認していた作業を自動化するためにこれらのスキルを開発しました。現在ではこれらのスキルを基盤とした「司令塔（command centre）」が整い、より多くの高品質なコンテンツ作成に集中できるようになりました。 ご自身の開発プロセスを振り返ってみてください。日次、週次、月次で繰り返している作業はありませんか？ それらをスキル化して貴重な時間を節約し、成果物の品質を高めましょう（あるいはその両方を実現しましょう）！ ### レベル3：特性（Traits） エージェントの性格、批評的な姿勢、思考様式そのものを変化させるスキルです。 このカテゴリで特に有名なのが、Matt Pocock氏による[`/grill-me`](https://github.com/mattpocock/skills)です。あまりの人気に、現在ではほとんどのエージェント実行環境（ハーネス）に標準機能として組み込まれています。このスキルの目的は、エージェントがユーザーに質問を投げかけることで必要な情報を引き出し、推測やハルシネーション（もっともらしい嘘）で要件を埋めてしまうのを防ぐことにあります。 私が気に入っている特性ベースのスキルには、[swarm-coding](https://skills.danicat.dev/agents/swarm-coding)、[double-diamond](https://skills.danicat.dev/agents/double-diamond)、[uno-reverse](https://skills.danicat.dev/agents/uno-reverse)などがあります。 Swarm codingは、サブエージェントの並列オーケストレーションに取り組むために私が最初に書いたスキルです。作成の全プロセスについては[サブエージェントの台頭]({{< ref "/posts/20260722-the-rise-of-the-subagents" >}})で詳しく書いていますので、仕組みに興味がある方はぜひご覧ください。 Double diamondはswarm codingの精神的後継であり、課題の探索（discovery）と構想（inception）のフェーズを組み込んでいます。アジャイル開発やデザイン思考に親しんでいる方ならお馴染みの手法でしょう。「発散」と「収束」を繰り返す原則に基づき、まずは問題空間を探索するために発散し、その後具体的な技術解へと収束させていきます。例えば、本サイトの大規模な新機能を計画する際は、次のようにセッションを開始できます： ```text /double-diamond I would like to plan phase 3 of this website. I want to improve the visualization of skill cards, add metrics, and a like/star button so we can rank skills by popularity. ``` Uno reverseは、実装を担当するエージェントたちの「エコーチェンバー（同調の罠）」を打破するために、あえて敵対的・批評的な人格を持たせたエージェントです。この敵対的エージェントは提案された実装を批判し、不要な肥大化を削ぎ落とす機会を探ることで、過剰設計（オーバーエンジニアリング）への対抗策として機能します。アーキテクチャレビューの健全性チェックとしてよく活用しています： ```text Please run a /double-diamond process to refine ADR-0002. At the review phase, use an /uno-reverse agent to antagonise the proposal and present the results. ``` これらのスキルは単体でも非常に強力ですが、組み合わせることで真価を発揮します。私のお気に入りは、1つのプロンプトで `/grill-me` + `/double-diamond` + `/uno-reverse` を同時に実行することです。これにより、モデルはまず要件を詰める質問をし、次に複数の実装案を深く調査・発散し、最後にそれらを批判的に検証して最適なアーキテクチャへと収束させてくれます。 新しいスキルの着想を得るには、これまでのキャリアの中で自分やチームの仕事の質を高めてくれた（人間的な）スキルやファシリテーション技術を思い出してみてください。特にサブエージェントの登場以降、AIに対してマネジメント手法を適用するケースが増えていますが、これは偶然ではありません。AIも放っておけば人間と同じような連携ミスや偏りを起こしてしまうからです。 ## 継続的な改善ループ スキルを作るのは素晴らしいことですが、その価値を最大限に引き出すには継続的な改善が不可欠です。私の場合、実際のセッションでスキルを使うたびに微調整（ブラッシュアップ）を行っています。実際の開発現場で使って初めて、粗削りな部分やコンテキストの不足、バグに気づくことが多いからです。また、新しい高性能モデルが登場した際もスキルを見直す絶好の機会です。モデルの推論能力向上に合わせてスキル側もアップグレードできます。 この作業を頻繁に行うため、私は[`/skill-optimizer`](https://skills.danicat.dev/agents/skill-optimizer)というスキルを作成しました。[agentskills.io](https://agentskills.io)に掲載されているベストプラクティスに独自のノウハウを加えたもので、段階的開示モデルが適切に機能しているか検証し、補助スクリプトでトークン数を推定して各セクションを適切なサイズに保ちます。また、スキルの説明文を内部実装ではなく「得られるメリット」に焦点を当てるよう最適化します。例えば最適化前の私の[search-analytics](https://skills.danicat.dev/analytics/search-analytics)スキルは、検索アルゴリズムの内部構造に関する不要な記述で溢れていましたが、これはスキルの利用には関係のないトークンの無駄でした。本当に必要なのは「データをどう読み込み、どう問い合わせるか」だけです。 手動での改善に加えて、自動化されたアプローチもあります。それが**agent dreaming**と呼ばれる、過去のエージェントセッションから教訓を抽出する概念です。Antigravityでは、`/learn`スラッシュコマンドを使ってこのドリーミングを実行できます。学習セッションを開始すると、エージェントは会話履歴からパターンを分析して改善点を探し、コンテキストファイルの更新、設定ガードレールの調整、あるいは新しいカスタムスキルの生成などを提案してくれます。例えば、長時間のデバッグセッションの後には、次のように実行するだけです： ```text /learn look at our debugging sessions with Ebitengine matrix transforms and state management. Extract the recurring bugs and fixes into a new documentation skill with clear anti-patterns and examples. ``` ## アクティベーション：暗黙的より明示的が勝る スキルの説明文（description）を微調整して、モデルが必要なときに100%自動でスキルを呼び出してくれるようにしようと、私は途方もない時間を費やしてきました。しかし、これまでのところその試みはすべて失敗に終わっています。高い確率で呼び出されるレベルには到達できますが、現時点で完璧な自動呼び出し率を達成するのは困難です。 そのため、私はPythonの設計哲学（Zen of Python）から古い格言を取り入れ、開発スタイルを改めました：*「暗黙的であるよりは、明示的であるほうがいい（Explicit is better than implicit）」*。エージェントが自発的に意図したスキルを呼び出してくれる善意に期待するのではなく、呼び出してほしいスキルとそのタイミングを明確に指示するのです。 Antigravityでは、スキルがスラッシュコマンドに自動マッピングされるため、`/swarm-coding`と入力するだけで即座にスキルが呼び出されます。また、スラッシュ記法はプロンプトの先頭だけでなく文中でも機能し、スラッシュ付きの単語がスキル名であるという明確なヒント（hint）としてモデルに伝わります。例えばプロンプトの末尾に`/grill-me`を添えるだけでも、エージェントは確実にそのスキルを発動します。最近のAntigravity CLIでは、複雑または曖昧な指示を与えた際に、ハーネスがプロンプトの末尾に自動で`/grill-me`を補完してくれる場面も見られます。 ## スキルが増えすぎることの弊害 スキルの活用を本格化させると、誰もが必ずある問題に直面します。段階的開示モデルがどれほど優れていても、何十ものスキルを常時インストールし続けると、MCPサーバーと同様にコンテキストの肥大化（Context Bloat）を招いてしまいます。 これを改善するには、手動の運用規律によるアプローチと、より高度な抽象化レイヤーを導入するアプローチの2つがあります。 1つ目の方法はシンプルです：真に必要な場合を除き、スキルをグローバルにインストールしないこと。スキルはユーザー単位（通常は`~/.agents/skills`）にインストールすることも、特定のワークスペース単位（プロジェクト内の`/.agents/skills`）にインストールすることも可能です。 この方法は小〜中規模では有効ですが、多数のプロジェクトに無数のローカルスキルが分散してくると管理が難しくなります。それらをどうやって最新に保つのか？ あるスキルの改善を他のプロジェクトにどう反映するのか？ そして`.agents`ディレクトリはGitにコミットすべきなのか？ といった問題が生じます。 この問題に対する最適な解決策は、「中央集約（またはフェデレーション）」と「出所（来歴・provenance）の追跡」を組み合わせることだと考えています。その第一歩となるのが**スキルカタログ**です。従来のスキル共有はGitのクローンやフォルダの手動コピーに頼っていましたが、公式のAgent Skills標準はリモートでの発見や配布をツール側に委ねています。そこで私は、Web経由でインデックスを公開するオンラインカタログマニフェストを`skills.danicat.dev`に作成しました。実際のマニフェストはこちらで確認できます：[https://skills.danicat.dev/catalog.json](https://skills.danicat.dev/catalog.json)。 スキルカタログは「スキルの発見可能性（discoverability）」の問題を解決します。エージェントにカタログを参照させることで、事前にインストールすることなく利用可能なスキルを把握させることができます。ただし、検索のたびにカタログ全体を読み込んでいてはコンテキスト肥大化を招くため、効率的なスキル検索手順が必要です。 また、カタログは「カタログからスキルへ」という一方向の流れを解決するだけです。スキルを最新に保つには、「スキルからカタログへ」という逆方向の参照が必要になります。これこそが私が「スキルの出所（skill provenance）」と呼んでいるものです。仕様では来歴の管理方法は規定されていませんが、管理には2つのアプローチがあります：1) 各インストールの出所を記録する外部スキルマネージャーを使うか、2) スキルのフロントマター（メタデータ）に直接カタログ情報を記載するかです。私は後者のほうが純粋に宣言的（declarative）であり、裏で何が起きているか明瞭であるため優れていると考えています。以下は私のカタログにおける典型的なフロントマターの例です： ```yaml --- name: swarm-coding description: > Orchestrates multi-agent hierarchical swarms using a divide-and-conquer architecture for complex, multi-system, or orthogonal engineering initiatives (e.g., concurrent backend, frontend, database, QA). Manages hierarchical Lead Agents and Specialists, disjoint work allocations, and strict parent-child communication. Activate whenever the user mentions 'swarm', requests multi-agent team coordination, or needs context isolation across multiple technical domains. license: Apache-2.0 metadata: category: agents tags: "swarm, subagents, parallel, orchestration, strategy, complexity, coordination" author: Daniela Petruzalek (daniela@danicat.dev) version: "0.2.0" catalog: https://skills.danicat.dev --- ``` `name`、`description`、`license`、`metadata`は仕様で定義された標準フィールドです。`metadata`の構造は自由ですが、私は推奨されている`version`と`author`を標準として採用し、さらに`category`、`tags`、`catalog`を拡張しました。カテゴリとタグは分類と検索を容易にし、`catalog`は正確な出所を記録します。これにより、スキルマネージャーは指定されたカタログURLにアクセスし、より新しいバージョンが存在するかどうかを確認するだけで簡単にアップデートを行えます。 エージェントが必要に応じて時々カタログを参照してスキルをインストールする程度であれば、カタログ全体の読み込みによるコンテキスト消費は見過ごせるかもしれません。しかし、理想を言えばもっとスマートな運用を行いたいところです。そこで登場するのが`kungfu`です。 ## "I know kung fu." [`kungfu`](https://github.com/danicat/kungfu)は、スキル管理を効率化するために私が開発したCLIツールです。名前の由来は映画『マトリックス』で主人公ネオの脳に武術のカンフーが直接「インストール」される有名なシーンから来ています。これこそが私がエージェントに対して抱いていた夢でした：必要な専門知識をいつでもオンデマンドで注入できるようにすることです。 私はエージェントに`kungfu` CLIの使い方を教える`kungfu`スキルを1つ用意しており、常時読み込んでおく必要があるのはこのスキルだけです。エージェントが新しいスキルを必要とした場合、`kungfu find`を使って名前、カテゴリ、タグ、説明文からカタログを検索します。レーベンシュタイン距離を用いた入力ミスの許容や「もしかして？」の提案機能も備わっています。検索結果からスコア順に最適なスキルが提示され、エージェントはそれを`kungfu load`でジャストインタイム（JIT）に即時読み込むか、`kungfu learn`で恒久的にインストール（グローバルまたはワークスペース）できます。以下の画像は、そのJIT読み込みの流れを示したものです： ![Terminal screenshot showing kungfu JIT loading the seo-optimizer skill](image.png "kungfu JIT loading the seo-optimizer skill") `kungfu`はインストールされたすべてのスキルを管理し、`kungfu list`で利用可能なスキル（ローカルまたはオンライン）を一覧表示できます。また、`kungfu update`はローカルのカスタマイズを保護しながら、サーバー側で更新されたスキルを安全にアップデートします。 `kungfu`はこの`catalog.json`の規約とフロントマターの拡張メタデータに依存しているため、リポジトリがマニフェストを公開しているか、スキル自身が出所を宣言している必要があります。コミュニティに存在する任意のスキルリポジトリとも連携できるよう、`~/.config/kungfu/state.json`にローカル状態を記録し、インストールの方法を問わずスキルの出所を追跡できるようにしています。 「マニフェストがあるのに、なぜわざわざメタデータにもカタログ情報を書くのか？」と思われるかもしれません。理由は2つあります。1つ目は宣言的な記述を好むからであり、2つ目は`kungfu`を使わずに手動でスキルを配置した場合でも、後から状態の調整やライフサイクル管理ができるようにするためです。 ## まとめ Agent Skillsは、静的な基盤モデルと日々の実践的なエンジニアリング・ワークフローとのギャップを埋めるための最も効果的な方法の1つです。古いSDKパターンを排除するためのシンプルなドキュメントスキルから始めるもよし、プロセススキルで反復的な分析作業を自動化するもよし、あるいは特性ベースのエージェントスウォームを探索するもよし、その投資対効果は極めて迅速に現れます。 [skills.danicat.dev](https://skills.danicat.dev)からアイデアを自由に取り入れたり、[`kungfu`](https://github.com/danicat/kungfu)を使ってオンデマンドでスキルを管理・読み込んだりしてみてください。どのような手法を選ぶにせよ、最も重要なのはプロセスを継続的に改善し、agentic codingの真の可能性を引き出し続けることです。