title: GitHub Copilot Agent Skills の書き方 ― Harness最適化でAIエージェントの性能を引き上げる
tags: GitHub Copilot, Agent Skills, VS Code, AI, Harness最適化
はじめに
GitHub Copilot のエージェントモードが日々進化する中、2025年末に Agent Skills というオープン仕様が公開されました。Agent Skills を使うと、Copilot に「自分だけの専門知識」を教え込み、特定のタスクを高精度に実行させることができます。
しかし、スキルを書いただけでは十分ではありません。エージェントの出力品質を決めるのは、プロダクトコードではなく Harness（ハーネス） — エージェントを取り巻く環境全体の設計です。
本記事では、Agent Skills 仕様 による基本的な書き方から、Harness最適化の7軸を踏まえた実践的な設計パターンまでを解説します。
Agent Skills は Anthropic が主導するオープン仕様 であり、GitHub Copilot だけでなく Claude Code や OpenAI Codex など複数の AI エージェントで利用可能です。
Agent Skills とは
Agent Skills は、AI エージェントに新しい能力や専門知識を与えるためのフォルダ形式の仕組みです。
一言でまとめると：
スキル = フォルダ +
SKILL.md（メタデータ＋指示書）
my-skill/
├── SKILL.md # 必須: メタデータ + 指示内容
├── scripts/ # 任意: 実行可能なコード
├── references/ # 任意: 参照ドキュメント
└── assets/ # 任意: テンプレート、リソース
スキルの動作フロー（Progressive Disclosure）
Agent Skills はコンテキストを効率的に管理するために 段階的開示（Progressive Disclosure） を採用しています。
| フェーズ | 読み込まれるもの | トークン目安 |
|---|---|---|
| Discovery |
name と description のみ |
～100 トークン |
| Activation |
SKILL.md 本文全体 |
～5,000 トークン推奨 |
| Execution |
scripts/, references/, assets/ 等 |
必要時のみ |
エージェント起動時に全スキルの name と description だけを読み、ユーザーの質問にマッチしたスキルだけが本文をロードします。この設計により、数十のスキルを登録してもパフォーマンスに影響しません。
💡 Harness 視点: Progressive Disclosure は Context Efficiency（コンテキスト効率）の根幹です。スキルが増えてもコンテキストウィンドウを圧迫しない仕組みが、仕様レベルで組み込まれています。
Harness（ハーネス）とは
Agent Skills がどんな仕組みかわかったところで、視点を一段引いてみましょう。
Harness とは、AI コーディングエージェントが動作する 周辺環境全体 を指します。Agent Skills はその構成要素の一つに過ぎません。
「エージェントの完了品質を向上させるには、プロダクトコードではなく Harness 設定を改善する」
Harness 最適化の 7 軸
everything-claude-code（ECC） が提唱する Harness Audit では、以下の 7 カテゴリでエージェント環境を評価します。
| # | カテゴリ | 評価内容 | 本記事での解説 |
|---|---|---|---|
| 1 | Tool Coverage | Skills/Agents/Hooks/Commands の網羅性 | → Orchestrator パターン |
| 2 | Context Efficiency | コンテキストウィンドウの効率利用 | → Context Efficiency |
| 3 | Quality Gates | テスト・検証パイプラインの充実度 | → Hooks（PostToolUse） |
| 4 | Memory Persistence | セッション間のメモリ永続化 | → Memory Persistence |
| 5 | Eval Coverage | 評価フレームワークの整備度 | → 検証ループ、バリデーション |
| 6 | Security Guardrails | セキュリティチェック機構 | → Hooks（PreToolUse） |
| 7 | Cost Efficiency | コスト最適化の仕組み | → Cost Efficiency |
本記事では、まず Agent Skills の書き方（基礎編）を押さえた上で、Harness 各軸を実践する設計パターン（応用編）を解説します。
スキルの配置場所
GitHub Copilot では、以下の 2 種類のスキルがサポートされています。
| 種別 | 配置場所 | スコープ |
|---|---|---|
| Project スキル |
.github/skills/ または .claude/skills/
|
リポジトリごと |
| Personal スキル |
~/.copilot/skills/ または ~/.claude/skills/
|
ユーザー全体（全プロジェクトで共有） |
Personal スキルは Copilot コーディングエージェントおよび GitHub Copilot CLI でのみ利用可能です。VS Code のエージェントモードでは .agents/skills/ も検索対象になります。
SKILL.md の書き方
最小構成
最もシンプルなスキルは、YAML フロントマターに name と description を書くだけです。
---
name: skill-name
description: A description of what this skill does and when to use it.
---
name と description の 2 フィールドだけが必須です。
フロントマター仕様
| フィールド | 必須 | 説明 |
|---|---|---|
name |
✅ | 最大64文字。小文字英数字とハイフンのみ。フォルダ名と一致させる |
description |
✅ | 最大1024文字。何をするか＋いつ使うかを記述 |
license |
- | ライセンス名またはファイル参照 |
compatibility |
- | 動作環境の要件（最大500文字） |
metadata |
- | 任意のキーバリュー（author, version 等） |
allowed-tools |
- | 事前承認するツールのリスト（実験的機能） |
name フィールドのルール
✅ pdf-processing # 小文字 + ハイフン
✅ data-analysis # OK
✅ code-review # OK
❌ PDF-Processing # 大文字NG
❌ -pdf # ハイフンで始まるのNG
❌ pdf--processing # 連続ハイフンNG
- Unicode 小文字英数字 (
a-z,0-9) とハイフン (-) のみ使用可能 - ハイフンで開始・終了してはならない
- 連続ハイフン (
--) は使用不可 - フォルダ名と一致させる（必須）
description フィールドのコツ
description はエージェントがスキルを「発見」するための最も重要なフィールドです。何をするか と いつ使うか の両方を含めましょう。
# ✅ Good - 具体的で、起動条件が明確
description: >
Extract PDF text, fill forms, merge files.
Use when handling PDFs.
# ❌ Bad - 曖昧すぎる
description: Helps with PDFs.
エージェントはこの description を見て「このスキルを使うべきか？」を判断します。キーワードを意識して書くことが重要です。
💡 Harness 視点:
descriptionの品質は Tool Coverage（ツール網羅性）に直結します。優れた description を書けば、スキルは確実に発見・起動されます。曖昧だと「存在するのに使われない」死蔵スキルになります。
オプションフィールド
---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
compatibility: Requires Python 3.14+ and uv
metadata:
author: example-org
version: "1.0"
allowed-tools: Bash(git:*) Bash(jq:*) Read
---
-
compatibility: 特定の環境が必要な場合のみ記述。ほとんどのスキルでは不要 -
allowed-tools: スキルが使用を事前承認するツール。スペース区切りで指定（実験的機能）
本文（Body）の書き方
フロントマターの後に続く Markdown 本文が、スキルの「指示書」になります。フォーマットに制約はありませんが、推奨される構成要素があります。
推奨する構成要素
1. ステップバイステップの手順
## データベースマイグレーション
以下の手順で実行してください:
```bash
python scripts/migrate.py --verify --backup
コマンドの変更やフラグの追加は行わないでください。
### 2. Gotchas（落とし穴）セクション
スキルで最も価値が高いのは、エージェントが自力では知り得ない「落とし穴」のリストです。
```markdown
## Gotchas
- `users` テーブルはソフトデリートを使用。クエリには必ず
`WHERE deleted_at IS NULL` を含めること
- ユーザーIDは DB では `user_id`、認証サービスでは `uid`、
課金APIでは `accountId`。すべて同じ値を指す
- `/health` エンドポイントは Web サーバーが動いていれば 200 を返す。
DB接続確認には `/ready` を使うこと
エージェントにミスを指摘・修正した際は、その内容を Gotchas セクションに追加しましょう。これがスキルを反復改善する最も効果的な方法です。
💡 Harness 視点: Gotchas の蓄積は Memory Persistence（メモリ永続化）の実践そのものです。セッション中に学んだ教訓をスキルに書き戻すことで、次のセッションでも同じミスを防げます。
3. 出力テンプレート
特定のフォーマットで出力させたい場合、テンプレートを提供すると信頼性が上がります。
## レポート構成
以下のテンプレートを使用し、分析内容に応じてセクションを調整してください:
```markdown
# [分析タイトル]
## エグゼクティブサマリー
[主要な発見の概要（1段落）]
## 主な発見
- 発見1（裏付けデータ付き）
- 発見2（裏付けデータ付き）
## 推奨アクション
1. 具体的で実行可能な推奨事項
2. 具体的で実行可能な推奨事項
### 4. チェックリスト（ワークフロー管理）
```markdown
## フォーム処理ワークフロー
Progress:
- [ ] Step 1: フォーム分析 (`scripts/analyze_form.py` を実行)
- [ ] Step 2: フィールドマッピング (`fields.json` を編集)
- [ ] Step 3: マッピング検証 (`scripts/validate_fields.py` を実行)
- [ ] Step 4: フォーム入力 (`scripts/fill_form.py` を実行)
- [ ] Step 5: 出力検証 (`scripts/verify_output.py` を実行)
5. 検証ループ
## 編集ワークフロー
1. 編集を実施
2. `python scripts/validate.py output/` でバリデーション実行
3. バリデーション失敗時:
- エラーメッセージを確認
- 問題を修正
- 再度バリデーション実行
4. バリデーション通過後のみ、次のステップへ
💡 Harness 視点: スキル内に検証ループを組み込むことは Eval Coverage（評価カバレッジ）の第一歩です。エージェントが自律的に出力を検証し、基準を満たすまでリトライする仕組みが品質を担保します。
実践例: サイコロを振るスキル
公式チュートリアルから、最もシンプルなスキルの例を紹介します。
ファイル作成
.agents/skills/roll-dice/SKILL.md を作成:
---
name: roll-dice
description: >
Roll dice using a random number generator.
Use when asked to roll a die (d6, d20, etc.),
roll dice, or generate a random dice roll.
---
To roll a die, use the following command that generates a random number
from 1 to the given number of sides:
```bash
echo $((RANDOM % <sides> + 1))
Replace <sides> with the number of sides on the die
(e.g., 6 for a standard die, 20 for a d20).
## 動作確認
1. VS Code でプロジェクトを開く
2. Copilot Chat パネルを開く
3. モードドロップダウンから **Agent** モードを選択
4. `/skills` と入力して `roll-dice` が表示されることを確認
5. 「Roll a d20」と入力
エージェントがスキルを検出し、ターミナルコマンドを実行して 1〜20 の乱数を返します。
# 実践例: 実用的なスキル設計
もう少し実践的な例として、コードレビュースキルを作ってみましょう。
```.agents/skills/security-review/SKILL.md```
```yaml
---
name: security-review
description: >
Perform security-focused code review. Use when reviewing code for
security vulnerabilities, checking for SQL injection, XSS, authentication
issues, or when asked to do a security audit of code changes.
metadata:
author: my-team
version: "1.0"
---
# セキュリティコードレビュー
## レビュー手順
1. すべてのDBクエリでパラメータ化クエリを使用しているか確認
2. 全エンドポイントに認証チェックがあるか検証
3. 並行処理コードにレースコンディションがないか確認
4. エラーメッセージが内部情報を漏洩していないか確認
## Gotchas
- `req.params` の値は常にサニタイズすること。Express はデフォルトでエスケープしない
- JWT トークンの有効期限は必ず確認。`exp` クレームなしのトークンを許容してはならない
- ファイルアップロードは拡張子だけでなく MIME タイプも検証すること
## 出力フォーマット
レビュー結果は以下の形式で報告:
| 重要度 | 場所 | 問題 | 推奨対応 |
|--------|------|------|---------|
| 🔴 HIGH | ファイル:行 | 内容 | 修正方法 |
| 🟡 MEDIUM | ファイル:行 | 内容 | 修正方法 |
| 🟢 LOW | ファイル:行 | 内容 | 修正方法 |
スキルのディレクトリ構成（大規模スキル）
スキルが大きくなってきたら、scripts/、references/、assets/ を活用します。
my-skill/
├── SKILL.md # コア指示（500行以内推奨）
├── scripts/
│ ├── analyze.py # 分析スクリプト
│ └── validate.py # 検証スクリプト
├── references/
│ ├── REFERENCE.md # 詳細リファレンス
│ └── api-errors.md # APIエラー対応表
└── assets/
├── template.md # 出力テンプレート
└── schema.json # データスキーマ
ファイル参照のコツ
SKILL.md から他のファイルを参照する際は、いつ読むべきか を明示しましょう。
<!-- ❌ 曖昧 -->
詳細は references/ を参照してください。
<!-- ✅ 条件付き -->
APIが 200 以外のステータスコードを返した場合は
`references/api-errors.md` を読んでください。
条件付きの参照にすることで、不要なコンテキスト消費を防げます。これも Context Efficiency を高める基本テクニックです。
ここから応用編です。 以上で Agent Skills の基本的な書き方を押さえました。ここからは Harness 最適化の 7 軸に沿って、エージェント環境全体を設計する実践パターンを解説します。
Orchestrator パターン ― 複数スキルを適切に使い分ける【Tool Coverage】
スキルが 1 つなら話は簡単ですが、プロジェクトに 5 個、10 個とスキルが増えてくると 「どのスキルをいつ使うか」 の設計が重要になります。ここでは GitHub Copilot のカスタマイズ機能を組み合わせて、Orchestrator（指揮者）がスキルを適切にディスパッチする方法を解説します。
GitHub Copilot のカスタマイズ階層
GitHub Copilot には複数のカスタマイズ機能があり、それぞれ役割が異なります。
| 機能 | ファイル | 適用タイミング | 用途 |
|---|---|---|---|
| Custom Instructions | copilot-instructions.md |
常時自動適用 | コーディング規約、レビュー基準 |
| Custom Agents | .github/agents/AGENT-NAME.md |
ユーザーが選択 | 専門ペルソナ（レビュアー、監査等） |
| Agent Skills | .github/skills/<name>/SKILL.md |
Copilot が自動選択 | タスク別のワークフロー |
| Subagents | （ランタイム） | エージェントが自動生成 | 隔離された並行タスク |
ポイント: Custom Instructions は「常にこう振る舞え」、Custom Agents は「この役割を演じろ」、Agent Skills は「このタスクにはこの手法を使え」という使い分けです。
description ベースの自動ルーティング
Copilot が複数のスキルから適切なものを選ぶメカニズムは、実はシンプルです。
ユーザーの質問
↓
全スキルの name + description を走査（Discovery）
↓
質問にマッチする description を持つスキルを選択（Activation）
↓
選ばれたスキルの SKILL.md 本文を読み込み（Execution）
つまり、description の書き方がルーティングの精度を決めます。
よくある失敗パターン
# ❌ description が曖昧 → 誤起動 or 起動しない
---
name: data-tool
description: Helps with data.
---
# ❌ description が重複 → どちらが選ばれるか不安定
---
name: csv-parser
description: Parse and process data files.
---
---
name: excel-processor
description: Process and analyze data files.
---
成功パターン: 起動条件を明示する
---
name: csv-parser
description: >
Parse CSV files: read, filter, aggregate, and export.
Use when working with .csv files or comma-separated data.
---
---
name: excel-processor
description: >
Process Excel workbooks: read sheets, apply formulas, create pivot tables.
Use when working with .xlsx/.xls files or Excel-specific features like formulas.
---
コツ: 「何をするか」+「いつ使うか（Use when...）」を明確に分離し、スキル間で起動条件が重複しないようにします。
AGENTS.md による Orchestrator 設計
複雑なワークフローでは、AGENTS.md を Orchestrator（全体指揮書） として使い、複数のスキルを段階的に呼び出すアーキテクチャが有効です。
全体像
AGENTS.md（ワークフロー全体のルール定義）
├── Phase 0: shikigami-planner（計画立案スキル）
├── Phase 1: shikigami-deep-research（調査スキル）
├── Phase 2: shikigami-consulting-framework（分析スキル）
└── Phase 3: shikigami-writing（レポート生成スキル）
AGENTS.md の設計パターン: WHEN/DO 構文
AGENTS.md にワークフロールールを WHEN/DO 構文 で定義すると、エージェントがタスクに応じて適切なスキルを選びやすくなります。
# My Project Workflow
## タスク分類ルール
### パターン1: 調査タスク
WHEN: ユーザーが「調査」「リサーチ」「分析」を依頼
DO:
1. planner スキルで計画を立案
2. deep-research スキルで情報を収集
3. writing スキルでレポートを生成
### パターン2: コードレビュー
WHEN: ユーザーが「レビュー」「コードチェック」を依頼
DO:
1. security-review スキルでセキュリティチェック
2. レビュー結果を指定フォーマットで出力
### パターン3: デプロイ
WHEN: ユーザーが「デプロイ」「リリース」を依頼
DO:
1. validate スキルで事前チェック
2. deploy スキルで実行
AGENTS.md はリポジトリのルートに配置します。Copilot はこのファイルをサードパーティエージェントの指示として自動的に読み込みます。
実践例: 4 スキル構成の Orchestrator
リサーチプロジェクトを例に、Orchestrator が 4 つのスキルを段階的にディスパッチする構成を示します。
ディレクトリ構成
.github/
├── skills/
│ ├── planner/
│ │ └── SKILL.md # Phase 0-1: 計画立案
│ ├── deep-research/
│ │ └── SKILL.md # Phase 2: 情報収集
│ ├── analyzer/
│ │ └── SKILL.md # Phase 3: フレームワーク分析
│ └── writer/
│ └── SKILL.md # Phase 4: レポート生成
├── agents/
│ └── researcher.md # Custom Agent: リサーチャー
└── AGENTS.md # Orchestrator（ワークフロー定義）
AGENTS.md（Orchestrator）
# Research Workflow Orchestrator
## ワークフロー
| Phase | スキル | 完了条件 |
|-------|--------|---------|
| 0 | planner | 調査計画がユーザーに承認された |
| 1 | deep-research | 3件以上のソースから情報収集完了 |
| 2 | analyzer | フレームワーク分析が完了 |
| 3 | writer | レポートが生成され品質チェック通過 |
## ルール
WHEN: 調査・リサーチ・分析の依頼を受けた場合
DO:
1. Phase 0 → planner スキルを使い、調査計画を立案
2. ユーザー承認を待つ（承認なしで Phase 1 に進んではならない）
3. Phase 1 → deep-research スキルで情報収集
4. Phase 2 → analyzer スキルでフレームワーク分析
5. Phase 3 → writer スキルでレポート生成
## 禁止事項
- Phase をスキップしてはならない
- search/visit 後は必ず結果を保存すること
- ユーザー承認ポイント（Phase 0, Phase 3）を飛ばしてはならない
planner スキル（Phase 0）
---
name: planner
description: >
Research planning and objective discovery. Use when starting
a new research task, investigation, or analysis project.
Structures the research goal into actionable steps.
---
# Research Planner
## 手順
1. ユーザーの依頼を 6 要素に構造化:
- PURPOSE: 何を決めたいか
- TARGET: 何を調べるか
- SCOPE: 調査の深さと幅
- TIMELINE: 期限
- CONSTRAINTS: 制約条件
- DELIVERABLES: 成果物
2. 構造化した内容をユーザーに提示し、承認を得る
3. 承認後、検索クエリのリストを作成
deep-research スキル（Phase 1）
---
name: deep-research
description: >
Iterative deep research with Think-Search-Report-Action cycle.
Use when collecting information from multiple sources,
verifying facts, or conducting web-based investigation.
---
# Deep Research
## サイクル
1. **Think**: 現状の知識ギャップを分析
2. **Search**: 日英バイリンガルで検索
3. **Report**: 収集情報を整理
4. **Action**: 追加調査が必要か判断
## Gotchas
- 検索後は必ず結果を保存すること（データ紛失防止）
- 単一ソースの情報は ⚠️ マークを付けること
- 3件以上のソースで交差検証すること
Custom Agent との組み合わせ
Custom Agent（.github/agents/AGENT-NAME.md）を使うと、ツール制限付きの専門ペルソナ を作れます。Orchestrator のスキルと組み合わせることで、より安全なワークフローが実現できます。
<!-- .github/agents/auditor.md -->
---
name: auditor
description: Read-only security auditor that reviews code without making changes.
tools:
- read_file
- grep_search
- semantic_search
---
# Security Auditor
You are a read-only security auditor. You MUST NOT modify any files.
Use the `security-review` skill when reviewing code for vulnerabilities.
Report findings using the skill's output format.
| 設計パターン | 構成 | 使いどころ |
|---|---|---|
| スキル単体 | SKILL.md のみ | 単発タスク（サイコロ、CSV変換等） |
| Orchestrator + 複数スキル | AGENTS.md + 複数 SKILL.md | 段階的ワークフロー（リサーチ、デプロイ等） |
| Agent + スキル | .agent.md + SKILL.md | ツール制限付き専門家（監査、レビュー等） |
| フルスタック | AGENTS.md + .agent.md + 複数 SKILL.md + MCP | 大規模プロジェクト運用 |
ルーティング精度を上げる 5 つのテクニック
1. description の棲み分け
スキル間で description のキーワードが重複しないよう、明確に境界を引きましょう。
# planner: 「計画」系のキーワード
description: >
Research planning and objective discovery.
Use when STARTING a new research, defining scope, or creating a plan.
# deep-research: 「収集」系のキーワード
description: >
Iterative deep research with web search.
Use when COLLECTING information, searching the web, or verifying facts.
# writer: 「生成」系のキーワード
description: >
Report generation and quality assurance.
Use when WRITING reports, articles, or documentation from research results.
2. ゲート条件（承認ポイント）を設ける
## Phase 遷移ルール
Phase 0 → Phase 1: ユーザー承認が必要 ⏸️
Phase 1 → Phase 2: 自動遷移（3件以上のソース収集完了時）
Phase 2 → Phase 3: 自動遷移（フレームワーク分析完了時）
Phase 3 → 完了: ユーザー承認が必要 ⏸️
3. 緊急度に応じたワークフロー分岐
## トリアージ
| 緊急度 | キーワード | ワークフロー |
|--------|-----------|------------|
| 通常 | （デフォルト） | Phase 0→1→2→3 フル実行 |
| 急ぎ | 「急ぎ」「今日中」「ASAP」 | Phase 0→1→3（分析スキップ） |
| 至急 | 「今すぐ」「至急」 | Phase 0→3（概要のみ） |
4. 禁止事項を明示する
エージェントが「やってはいけないこと」を明確にすると、誤動作が減ります。
## 禁止事項
- ユーザー承認なしで Phase を進めてはならない
- 検索結果を保存せずに次のアクションに進んではならない
- Phase をスキップしてはならない（緊急トリアージ時を除く）
5. タスク分類の判定ツリーを書く
エージェントが迷わないよう、明示的な判定ツリーを提供します。
## タスク分類
1. 外部情報が必要か？
- YES → リサーチワークフロー（planner → deep-research → writer）
- NO → 次へ
2. コードの変更が必要か？
- YES → コーディングタスク（直接対応）
- NO → 次へ
3. レビュー・監査か？
- YES → auditor エージェント + security-review スキル
- NO → 通常の質問として回答
Hooks ― スキルの実行を自動で検証する【Quality Gates / Security Guardrails】
GitHub Copilot は Hooks 機能をサポートしており、エージェントのライフサイクルイベントに自動処理を差し込めます。これは Harness 最適化の Quality Gates（品質ゲート） と Security Guardrails（セキュリティガードレール） に直結します。
Hooks のライフサイクルイベント
| イベント | タイミング | 用途例 |
|---|---|---|
| PreToolUse | ツール実行前 | 危険コマンドのブロック、設定ファイル保護 |
| PostToolUse | ツール実行後 | 自動フォーマット、品質チェック、型チェック |
| Stop | エージェント応答完了時 | セッション保存、コスト追跡 |
PostToolUse: ファイル編集後の自動品質チェック
エージェントがファイルを編集するたびに自動で品質チェックを実行する設定例です。
{
"hooks": {
"postToolUse": [
{
"matcher": "Edit|Write",
"command": "npx eslint --fix ${file}",
"description": "ファイル編集後に自動 lint + fix"
}
]
}
}
Hooks により、エージェントが壊れたコードをコミットするリスクを大幅に低減できます。PostToolUse で lint、フォーマッター、型チェックを自動実行するのが品質ゲートの基本パターンです。
PreToolUse: セキュリティガードレール
Harness 最適化の Security Guardrails の観点では、エージェントが危険な操作を行う前にブロックする多層防御が重要です。
{
"hooks": {
"preToolUse": [
{
"matcher": "Bash",
"command": "node scripts/hooks/block-dangerous-commands.js",
"description": "rm -rf, git push --force 等の危険コマンドをブロック"
},
{
"matcher": "Write|Edit",
"command": "node scripts/hooks/config-protection.js",
"description": "Linter/Formatter 設定ファイルの変更をブロック"
}
]
}
}
多層防御の設計
| レイヤー | 機構 | 役割 |
|---|---|---|
| Layer 1 | PreToolUse Hooks | 危険コマンドの事前ブロック、シークレット漏洩検出 |
| Layer 2 | Security Review スキル | 脆弱性分析、セキュリティチェックリスト適用 |
| Layer 3 | Custom Agent（ツール制限） | 読み取り専用の監査エージェント |
| Layer 4 | Human Review | セキュリティ関連の最終判断 |
Context Efficiency ― コンテキストを賢く使う【Context Efficiency】
Harness 最適化の Context Efficiency は、限られたコンテキストウィンドウをいかに効率的に使うかの指標です。Agent Skills の設計にも直結します。
Progressive Disclosure の実践
前述の通り、Agent Skills は段階的開示で設計されています。これ自体がコンテキスト効率の最適化パターンです。
| レベル | 読み込み量 | タイミング |
|---|---|---|
| L1: メタデータ | ～100 トークン/スキル | 常時（全スキル） |
| L2: 本文 | ～5,000 トークン | Activation 時のみ |
| L3: 参照ファイル | 必要量のみ | Execution 時のみ |
戦略的コンパクション
長いセッションでは、論理的な区切りでコンテキストを整理する 戦略的コンパクション が有効です。
| フェーズ遷移 | コンパクション | 理由 |
|---|---|---|
| 調査 → 計画 | ✅ する | 調査コンテキストは嵩張る。計画が蒸留結果 |
| 計画 → 実装 | ✅ する | 計画はファイルに記録済み。コンテキストを解放 |
| 実装 → テスト | ⚠️ 場合による | テストが直近コードを参照するなら保持 |
| デバッグ → 次機能 | ✅ する | デバッグトレースが次の作業を汚染 |
| 実装の途中 | ❌ しない | 変数名・ファイルパス・部分状態を失うコストが高い |
MCP サーバーのコンテキスト消費に注意
MCP サーバーは「有効化するだけ」でツール定義分のコンテキストを消費します。200K コンテキストウィンドウが、MCP ツール定義だけで 70K に縮小するケースもあります。
推奨ルール:
- 同時に有効化する MCP は 10 個以下
- 使わない MCP は無効化する
- CLI ツールで代替可能なら MCP より CLI を使う（例:
gh> GitHub MCP）
Cost Efficiency ― スキル設計でコストを最適化する【Cost Efficiency】
Harness 最適化の Cost Efficiency はスキル設計にも影響します。
モデルルーティングの考え方
タスクの複雑さに応じて最適なモデルを選択する戦略です。スキルの description にタスクの複雑度ヒントを書くことで、間接的にモデル選択を助けられます。
| タスク種別 | 推奨モデル | コスト比 |
|---|---|---|
| ファイル探索・読み取り | Haiku 相当（軽量） | 1x |
| 日常コーディング・レビュー | Sonnet 相当（標準） | ～4x |
| 複雑な設計・マルチステップ推論 | Opus 相当（高性能） | ～19x |
スキル設計でのコスト削減ポイント
| テクニック | 効果 |
|---|---|
| SKILL.md を 500 行以内に抑える | Activation 時のトークン消費を制限 |
| 参照ファイルを条件付きにする | 不要な reference のロードを防止 |
| Subagent 向けスキルを分離する | 軽量モデルで実行可能なタスクを切り出す |
| Gotchas で試行錯誤を減らす | エージェントの無駄な再試行を防止 |
Memory Persistence ― セッションを超えた学習【Memory Persistence】
Harness 最適化の Memory Persistence は、セッション間で知識を永続化する仕組みです。
スキルでメモリを設計する
スキルの中に「学びをファイルに書き出す」指示を含めることで、セッションを超えた知識蓄積が可能になります。
---
name: learning-capture
description: >
Capture learnings and patterns from completed tasks.
Use when finishing a task, resolving a bug, or completing a review
to record what was learned for future sessions.
---
# Learning Capture
## タスク完了時の手順
1. 今回のタスクで発見したパターン・落とし穴を整理
2. 以下のフォーマットで `.github/learnings/` に記録:
```markdown
## [日付] [タスク概要]
### 発見
- [具体的な発見事項]
### Gotchas 追加候補
- [関連スキルに追記すべき落とし穴]
- 関連スキルの Gotchas セクションを更新
## コンパクション後も生き残るもの
セッション中のコンパクションで何が保持され、何が失われるかを意識しましょう。
| ✅ 保持される | ❌ 失われる |
|-------------|------------|
| ルールファイルの指示 | 中間的な推論・分析 |
| タスクリスト | 過去に読んだファイル内容 |
| ディスク上のファイル | 複数ステップの会話コンテキスト |
| Git 状態 | ツール呼び出し履歴 |
:::note info
重要な中間結果は「ファイルに書き出す」指示をスキルに含めることで、コンパクション耐性を確保できます。これが Memory Persistence の基本原則です。
:::
:::note info
**Eval Coverage（7軸の第5軸）** について: Agent Skills における出力評価は、スキル内の **検証ループ**（「本文の書き方」セクション参照）と、[skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) による `SKILL.md` 自体の静的バリデーション（「ベストプラクティスまとめ」参照）で実現します。CI に `skills-ref validate` を組み込むことで、スキルのフォーマット違反を自動検出できます。
:::
# ベストプラクティスまとめ
## 1. 実体験をベースにする
❌ LLMに「コードレビューのスキルを作って」と丸投げ
→ 汎用的で当たり前の内容しか出ない
✅ 実際の作業からパターンを抽出
→ プロジェクト固有のAPI/エッジケース/規約が含まれる
スキル作成のベストな方法は：
1. **実タスクで会話** → エージェントと一緒に作業し、修正を加える
2. **パターンを抽出** → うまくいった手順、修正した箇所、提供したコンテキストを抽出
3. **スキル化** → 抽出したパターンを SKILL.md に構造化
## 2. エージェントが知らないことだけ書く
```markdown
<!-- ❌ 冗長 — エージェントはPDFが何か知っている -->
## PDF テキスト抽出
PDF (Portable Document Format) は、テキスト、画像、その他のコンテンツを含む
一般的なファイル形式です。テキストを抽出するには...
<!-- ✅ 簡潔 — エージェントが知らない固有情報だけ -->
## PDF テキスト抽出
pdfplumber で抽出。スキャン文書の場合は pdf2image + pytesseract にフォールバック。
3. デフォルトを示し、選択肢を減らす
<!-- ❌ 選択肢が多すぎる -->
pypdf, pdfplumber, PyMuPDF, pdf2image を使えます...
<!-- ✅ デフォルトを明示 -->
pdfplumber でテキスト抽出してください。
OCR が必要なスキャンPDFの場合のみ pdf2image + pytesseract を使用。
4. コンテキストを節約する
| 指針 | 説明 |
|---|---|
| 500行以内 |
SKILL.md は 500 行（5,000トークン）以内が推奨 |
| 参照は条件付き |
references/ のファイルは「いつ読むか」を明示 |
| 宣言より手順 | 「こう出力せよ」より「こう進めよ」が再利用性が高い |
| 反復改善 | エージェントのミスを Gotchas に追記し続ける |
5. バリデーションを活用する
skills-ref ライブラリでスキルを検証できます。
skills-ref validate ./my-skill
6. Harness 7 軸で自己評価する
スキルを書いたら、以下の 7 軸で自分の環境を振り返りましょう。
| 軸 | 自問 | 対応アクション |
|---|---|---|
| Tool Coverage | 必要なスキル・エージェントは揃っているか？ | 不足するスキルを追加 |
| Context Efficiency | SKILL.md は 500 行以内か？参照は条件付きか？ | Progressive Disclosure で最適化 |
| Quality Gates | 編集後の自動チェックはあるか？ | PostToolUse Hooks を設定 |
| Memory Persistence | 学びをファイルに書き出しているか？ | learning-capture スキルを導入 |
| Eval Coverage | スキルの出力を検証する仕組みはあるか？ | 検証ループ・チェックリストを追加 |
| Security Guardrails | 危険な操作をブロックしているか？ | PreToolUse Hooks で多層防御 |
| Cost Efficiency | 不要なコンテキスト消費はないか？ | MCP 管理、モデルルーティング意識 |
GitHub Copilot での対応状況
| 環境 | Agent Skills 対応 |
|---|---|
| VS Code Insiders（エージェントモード） | ✅ |
| VS Code 安定版 | 近日対応予定 |
| Copilot コーディングエージェント | ✅ |
| GitHub Copilot CLI | ✅ |
| Claude Code | ✅ |
まとめ
Agent Skills は「フォルダ + SKILL.md」という極めてシンプルな構成で、AI エージェントに専門知識を教える仕組みです。
ポイントを振り返ります：
-
最小限で始める —
nameとdescriptionの 2 フィールドだけでスキルは動く - description が命 — エージェントがスキルを発見できるかは description 次第
- 実体験から作る — LLM に丸投げするのではなく、実作業のパターンを抽出する
- コンテキストを節約 — 500行以内、Progressive Disclosure を意識する
- 反復改善 — エージェントのミスを Gotchas に追記して育てる
- Orchestrator で束ねる — スキルが増えたら AGENTS.md + WHEN/DO 構文でワークフローを設計する
- Harness 7 軸で評価 — Tool Coverage / Context Efficiency / Quality Gates / Memory Persistence / Eval Coverage / Security Guardrails / Cost Efficiency
スキルは一度書いたら終わりではなく、使いながら育てるものです。単体スキルから始めて、Orchestrator パターンへ拡張し、Harness 全体を 7 軸で最適化していきましょう。
成長ステップ:
[1] 単体スキル → SKILL.md 1つから始める
[2] 複数スキル → description の棲み分けを設計
[3] Orchestrator → AGENTS.md でワークフロー管理
[4] Hooks 統合 → 品質ゲート + セキュリティガードレール
[5] Harness 最適化 → 7軸スコアで継続的に改善
参考リンク
Agent Skills
- Agent Skills 公式サイト
- Agent Skills 仕様
- Agent Skills GitHub リポジトリ
- GitHub Docs: エージェントのスキルについて
- Copilot カスタマイズチートシート
- Example Skills（Anthropic）
- Quickstart: 初めてのスキル作成
- Best Practices
Harness 最適化
- 【Claude Code】Harness最適化 完全ガイド — 本記事の Harness 7軸の参照元
- everything-claude-code (GitHub) — Harness Audit フレームワーク