Agent Skills 完全ガイド（初級編）：エージェントに配れる再利用可能な手順知識パッケージ¶
この記事の対象者
- Agent Skills を初めて知った方
- AIエージェントの「手順知識」を再利用可能にしたい方
- GitHub Copilot / VS Code / Claude Code / Codex で共通のスキルを作りたい方
"エージェントに配れる、再利用可能な手順知識パッケージ" としての Agent Skills を、まず「作って・効かせる」ところまで解説します。
迷ったら先に読む（3分で地図が掴める）
pre-built skills と SKILL.md の違い、発動条件、使い分けだけ先に整理したい方は
Agent Skills 超入門：pre-builtとSKILL.mdの違いが3分でわかる を先に読むのが効果的です。
Agent Skills とは何か（最短理解）¶
Agent Skills は、指示（Markdown）＋補助リソース（任意のスクリプト/参照/テンプレ）を1つのフォルダにまとめたもので、エージェントが「必要なときだけ」読み込んで作業精度を上げるためのオープン標準フォーマットです。
Progressive Disclosure（段階的開示）がポイント
- 起動時に読むのは各スキルの
name/description（メタデータ）だけ - 必要と判断されたときに
SKILL.md本文 - さらに必要なら
references/やscripts/等の追加ファイル
この"省コンテキスト設計"が、Agent Skills の効率性を支えています。
何がうれしいか（プロンプト／カスタム指示／MCP との違い）¶
VS Code のドキュメントでも、カスタム指示は「常時適用のコーディング規約」寄り、スキルは 「手順・ワークフロー・資産込みの専門能力」 と整理されています。
| 使い分け | 向いているもの | 典型例 |
|---|---|---|
| カスタム指示 | ほぼ全タスクに共通のルール（常時） | 命名規約、Lint方針、PRの粒度 |
| Agent Skills | 条件一致時にだけ読み込む"手順知識＋資産" | リリース手順、障害一次切り分け、Terraformレビュー手順 |
MCPとの関係は「競合」ではなく「分担」
MCP が"できること（API/操作）"を増やし、Skills が"どう使うか（手順知識）"を与える、という整理が一般的です（VS Code / Claude まわりでもこの方向）。
どこで使えるか（2026年2月時点の対応状況）¶
Agent Skills は急速に普及しており、主要ツールで相互運用が進んでいます。
公式に対応を発表しているツール¶
| ツール | 対応状況 | 備考 |
|---|---|---|
| GitHub Copilot |  対応（2025/12/18発表） | Copilot coding agent, CLI, VS Code agent mode で利用可能 |
| VS Code | Stable版で対応済み | VS Code 1.109+ で chat.useAgentSkills を有効化 |
| OpenAI Codex | 対応 | CLI/IDE拡張で SKILL.md + scripts/references/assets 形式をサポート |
| Cursor | 対応 | agentskills.io に採用ツールとして掲載 |
| Claude Code | 対応 | Skills の起源。.claude/skills が元の配置 |
その他、Amp, Letta, goose, OpenCode なども採用しています。
標準仕様¶
agentskills.io で仕様とリファレンス SDK が公開されています。Anthropic が 2025年12月にオープン標準として公開し、Microsoft（VS Code / GitHub）が即座に採用したことで業界標準化が進んでいます。
最小構成：まず1個つくる（"動くドキュメント"として）¶
仕様上の最小構成はこれだけです：
skill-name/ディレクトリSKILL.md（YAML frontmatter 必須）
フォルダ配置¶
リポジトリ内に以下を作成します：
.github/skills/<skill-name>/SKILL.md ← 推奨（GitHub Copilot / VS Code 共通）
.claude/skills/ ← 互換目的のレガシー配置（引き続きサポート）
配置の互換性
GitHub Copilot は .claude/skills/ も自動で認識するため、既存の Claude Code 用スキルをそのまま使えます。
例：クラウドエンジニア向け「Terraform Plan レビュー」スキル¶
以下は「まず効く」粒度のサンプルです（短く・判断基準を明示・必要なら参照へ逃がす）。
# .github/skills/terraform-plan-review/SKILL.md
---
name: terraform-plan-review
description: Terraform plan の差分レビューを標準化する。planの変更点を分類し、破壊的変更・権限変更・ネットワーク変更・コスト影響を優先的に点検する。Terraform, plan, diff, infrastructure review, IAM, network, cost の話題で使用する。
license: Proprietary
metadata:
author: platform-team
version: "0.1"
compatibility: Requires terraform CLI and access to repo IaC code. (Optional) Internet access for provider docs.
---
## Goal
Terraform plan のレビューを「抜け漏れなく・同じ観点で」実施する。
## Inputs
- `terraform plan` の出力（テキスト or JSON）
- 変更対象のモジュール/環境（dev/stg/prod）
## Procedure (Step-by-step)
1. **変更の分類**（Resource種別 / 影響範囲 / 環境）
2. **破壊的変更の検出**（delete/replace）
3. **IAM/権限**（role/policy/binding の追加・緩和）
4. **Network**（ingress/egress, public exposure, SG/NSG）
5. **データ保護**（KMS, encryption, backup, retention）
6. **コスト影響の推定**（新規大物リソース、スケール増）
7. **ロールバック方針**（apply失敗時、state整合性）
## Output format
- Summary: 何が変わるか（3行）
- Risks: 重大リスク（箇条書き）
- Checks done: 実施した観点チェック
- Questions: 不明点（PRコメント用）
## Common pitfalls
- replace が "実質ダウンタイム" になる（LB/DB/VM）
- IAM 変更が想定外の権限拡大
- Network のpublic化（0.0.0.0/0）混入
この例は仕様上も妥当です：
SKILL.mdは YAML frontmatter（name/description必須）＋ Markdown 本文nameは小文字・数字・ハイフンのみ、64文字以内の制約があり、ディレクトリ名と一致が必要
初級で押さえる「効くスキル」の作り方¶
description に"発火キーワード"を入れる¶
スキルは起動時に name/description を読み、適合すると判断したら本文をロードします。そのため description は「何をするか」に加え「いつ使うか（キーワード）」を明確に入れるのが重要です。
良い例
description: Terraform plan の差分レビューを標準化する。Terraform, plan, diff, infrastructure review, IAM, network, cost の話題で使用する。
悪い例
description: インフラのレビューを助ける。
本文は手順と出力フォーマットを固定する¶
初級で最も効果が出るのは、手順の順序と成果物の型を固定することです（レビュー観点、チェックリスト、報告フォーマット等）。
長くなったら references/ に逃がす¶
仕様としても、詳細は references/ に分割し、必要時にだけ読ませるのが推奨です。5000トークン以下、500行以下が目安です。
検証（validate）を入れる¶
公式のリファレンス SDK として skills-ref validate が提供されています。CI に入れるとチーム運用が安定します。
# インストール（Python環境）
pip install skills-ref
# スキルの検証
skills-ref validate ./my-skill
# プロパティの読み取り（JSON出力）
skills-ref read-properties ./my-skill
name フィールドの仕様詳細¶
公式仕様で定義されている name の制約：
| 制約 | 内容 |
|---|---|
| 文字数 | 1〜64文字 |
| 使用可能文字 | 小文字アルファベット（a-z）、数字（0-9）、ハイフン（-） |
| 開始・終了 | ハイフンで始まってはいけない、ハイフンで終わってはいけない |
| 連続ハイフン | -- は不可 |
| ディレクトリ名 | 親ディレクトリ名と一致必須 |
有効・無効な例
- 有効:
pdf-processing,data-analysis,code-review,terraform2 - 無効:
PDF-Processing（大文字）,-pdf（先頭ハイフン）,pdf--processing（連続ハイフン）
次のステップ（中級編の予告）¶
初級を作ったあとに伸ばすなら、次はここです。
- スキル設計パターン: チェックリスト型／生成テンプレ型／自動実行（scripts）型
- CI/CD統合:
skills-ref validate、lint、バージョニング、配布 - セキュリティ/ガバナンス:
allowed-tools（実装差あり）とレビュー規約 - 複数スキル合成: リリース、障害対応、変更管理など"一連の業務フロー"を分割して連携
関連記事¶
- Skills の陳腐化は避けられない──検知・回復・局所化の運用設計 ── 作った Skill の保守・評価ループ設計
- Claude Agent Skillsが発火しない原因は「description」 ── description 設計パターンと発火率改善
- Agent Skills 超入門：pre-builtとSKILL.mdの違い ── 3分で概要を掴む
- Agent Skills 現場ユースケース集 ── 実務ユースケースと効果測定
- SkillsMP レビュー2026 ── マーケットプレイス活用ガイド
参考リンク¶
- Agent Skills 公式仕様
- GitHub Copilot Skills 発表（2025/12/18）
- VS Code Agent Skills ドキュメント
- OpenAI Codex Skills
- GitHub Docs - About Agent Skills
- Anthropic Skills リポジトリ
- GitHub awesome-copilot（コミュニティスキル集）
まとめ¶
| 項目 | 内容 |
|---|---|
| Agent Skills とは | 指示（SKILL.md）＋任意のスクリプト/参照/資産をフォルダで配る「オープン標準」 |
| 段階的開示 | 起動時は name/description → 必要時に本文 → さらに追加リソース |
| 対応ツール | GitHub Copilot, VS Code, OpenAI Codex, Cursor, Claude Code ほか |
| 推奨配置 | .github/skills/<skill-name>/SKILL.md |
| 最小構成 | YAML frontmatter（name/description 必須）＋ Markdown 本文 |
| 初級の勝ち筋 | description に発火キーワード、手順＋出力フォーマット固定、references/ 分割 |
| 検証 | skills-ref validate を CI に組み込み |