🔷概要（この記事で得られること）

本記事では、SKILLS（エージェント用スキル）の概念、設計方針、運用・大量管理の方法、実践的なレビューワークフローへの適用例を段階的に解説します。SKILLSを用いることで、エージェントが自律的に最適な手順を選択し実行する仕組みを構築でき、レビュー自動化や専門化したサブエージェント運用の導入による効率化が期待できます。

🔹1. SKILLSの基礎：概念と構成要素

概要： SKILLSは各ドメインに特化した記述（description）と、実行手順を記した詳細な指示を組み合わせたもので、エージェントは要求に応じてdescriptionを参照し該当するスキルを読み取り実行します。

▸ SKILLSの構成（Agent Skills 仕様に基づく）
• ディレクトリ構成（公式仕様に基づく）：スキルはフォルダ単位で管理し、少なくとも SKILL.md をルートに置きます。オプションで scripts/、references/、assets/ を追加できます。

• SKILL.md の frontmatter（必須）：YAML frontmatter が必要で、少なくとも name（1〜64文字、小文字英数字とハイフンのみ、親ディレクトリ名と一致）と description（1〜1024文字、何をするかといつ使うかを明記）が含まれます。オプションで license、compatibility、metadata、allowed-tools などを宣言できます。

name/descriptionなどのメタ情報は起動前に軽量にロードされ、スキルが選ばれた場合に本文や追加リソースを読み込む手法が推奨されています。これにより多数のスキルを効率的にフィルタできます。

• 本文：frontmatter の後に続く Markdown 本文が実際の手順や補足になります。本文には手順、入出力例、エッジケース、参照の書き方などを含めると良く、エージェントはスキルを有効化した際にこの本文を読み込みます。長い参照資料は references/ に分けることで、本文を短く保ちつつ必要時に参照させる設計（プログレッシブディスクロージャ）が推奨されています。

※skills-ref で frontmatter の検証や命名規則チェックを行えます。SKILL.md は 500 行以下に保ち、詳細は別ファイルに分割することが推奨されています。

▸ MCPや一般的なエージェントとの関係
• MCP（Model Context Protocol）や一般的なエージェント仕組みと類似点が多いですが、SKILLSは“選択可能な小さな専門単位”を明確に定義し、複数のスキルが同時に評価・発火される点で運用の柔軟性が増します。

▸ 実行トリガーと挙動の差分
• 現時点では、実装により発火条件や挙動が異なる場合があります。例えばCodex CLI実装では「適合する全スキルを発火」する挙動が確認されています。一方で、GitHub Copilotの一部実装ではnameを明示しないと発火しない等の差があります。運用時は対象プラットフォームの挙動を確認してください。

🔹2. SKILLS設計のベストプラクティス

概要： スキルは適切な粒度で分割し、明瞭なdescriptionと再利用可能な手順を用意することで、AIが自律選択しやすくなります。

▸ 粒度の設計
• 小さすぎるとノイズが増え、大きすぎると再利用・組合せが困難になります。レビュー用途であれば「構文チェック」「セキュリティ指摘」「設計観点（アーキテクチャ）」など、責務ごとにスキルを分けると良いです。

▸ descriptionの書き方
• descriptionは短く、検索や判定に使えるキーワードを含めます。目次代わりになるように主要項目を列挙すると、エージェントがマッチングをしやすくなります。

▸ 手順の書き方
• 実行手順、期待出力例、失敗時の対処、参照URL、サンプルコードを含めると親切です。

以下は簡易的なSKILL例（参考）:

# SKILL.md
---
name: "csharp-code-review"
description: "C# コードのスタイル、設計、セキュリティ観点からのレビューを実施します。ユーザーが「このソースをレビューして」「レビューを実行して」と言ったとき、本スキルを使用してください。"
metadata:
  domain: "review/csharp"
  instructions: "file:///path/to/instructions/csharp_review.md"
---
## C#コードレビュー手順
1. 提供されたC#ソースコードを解析します。
2. 以下の観点でレビューを行います：
   - コードスタイル（命名規則、一貫性）
   - 設計パターンの適用
   - セキュリティリスク（例：SQLインジェクション、XSS）
3. 各指摘に対し、具体的な改善案を提示します。
4. 最終的なレビュー報告書を生成します。
## 参考資料
- [C# コーディング規約](https://docs.microsoft.com/ja-jp/dotnet/csharp/programming-guide/inside-a-program/coding-conventions)
- [OWASP Top 10](https://owasp.org/www-project-top-ten/)

実行時はエージェントが description を元にスキルをフィルタし、本文を取得＆実行します。

🔹3. 運用と自動化：大量のSKILLを安全に管理する方法

概要： テンプレート化、自動生成（ビルダー）、バージョン管理、隔離実行が重要です。特に多数のスキルを運用する際はテストとガードレールを整備してください。

▸ スキルビルダーとテンプレート化
• スキルビルドを行うエージェントを作成し、同一フォーマットで出力するためのテンプレートを用意し、大量作成すると効率的です。

▸ バージョン管理とテスト
• 各スキルはコードと同様にリポジトリで管理しましょう。誤った挙動を防ぐため、サンドボックス環境で実行するテストプロンプトを用意します。

▸ 隔離実行：Git worktrees とサブエージェント
• VS Code が示す worktree を活用すると、Backgroundエージェントがワークスペースに与える影響を限定できます。サブエージェントを組み合わせることで、専門化された小さなエージェント群を安全に運用できます。

💡 Tips: テンプレート生成時に手順内で外部コマンドを呼ぶ場合は、必ず安全な実行パターン（タイムアウト、入力サイズ制限、ログ収集）を組み込みましょう。

🔹4. 実践例：レビューワークフローへの適用

概要： 複数スキルを並列で発火させ、専門化された指摘を統合するワークフローを紹介します。

▸ 並列レビューと専門化
• プルリク（PR）に対し、複数のレビュー用スキル（例：csharp-style, security-check, performance-hint）を同時に走らせます。各スキルは独立してレポートを出力し、最終的に統合レポートを作るエージェントが指摘を集約します。

▸ VS Code カスタムエージェントの活用
• VS Code のカスタムエージェント機能では、UIからスキルを起動したり、サブエージェントとしてワークフローを分割して実行できます。

▸ フロントエンド開発との組合せ
• コンポーネント駆動開発（Storybookなど）をプロジェクトに導入しておくと、UIに関するスキルがテスト対象コンポーネントを読み取りやすくなり、AIが適切なコンポーネントを参照して修正提案を行いやすくなります。Blazor環境では BlazingStory のような代替ツールを検討してください。

🔹5. まとめ：導入の判断基準と次の一歩

概要： SKILLSは適切に設計・運用すればレビュー自動化や専門的なタスク分担に強力な効果を発揮します。小さく始めて評価→拡張が現実的な導入パターンです。

▸ 導入判断のポイント
• 繰り返し発生するレビュー作業 が多い場合は導入の効果が高いです。

• ドメインごとに明確なルールがある（例：セキュリティチェック、スタイルガイド）ことが望ましいです。

▸ 初期に作るべきスキル候補
• コードスタイルチェック

• セキュリティベーシックチェック（危険なAPI、入力検証の不足等）

• テストカバレッジの簡易検査

▸ ✅導入の進め方（小さく始めるモデル）
• まずは1〜2個のスキルを作成し、PRやコミット(SHA-1)指定で動かしてみる。

• 出力を人がレビューし、誤検出・未検出のフィードバックを元にスキルを改善する。

• 運用が安定してきたらスキルを分割・テンプレ化し、スキルビルダーで量産する。

参考・補足

Visual Studio Code — Custom Agents: https://code.visualstudio.com/docs/copilot/customization/custom-agents
VS Code updates v1.107 — Run agents as subagents: https://code.visualstudio.com/updates/v1_107#_run-agents-as-subagents-experimental
VS Code updates v1.107 — Git worktrees: https://code.visualstudio.com/updates/v1_107#_isolate-background-agents-with-git-worktrees
Storybook: https://storybook.js.org/
BlazingStory: https://blazingstory.github.io/docs/
SKILL ビルダー（参考記事）: https://zenn.dev/openjny/articles/264b7b02b406f0

※お役に立てたらストック、いいねをよろしくお願いします！！