DevOps Agent カスタムスキル実践ガイド — SKILL.mdの書き方から運用サイクルまで

「DevOps Agent、入れたはいいけど汎用調査しか動かないんだよね」

AWS DevOps Agent を導入した直後は、たしかに動きます。CloudWatch アラームから調査レポートが届き、「おお、ちゃんと分析してる」と感動する。しかし数週間もすると、レポートの内容がどれも似たり寄ったりであることに気づきます。自社のアーキテクチャ特有のチェック項目が抜けていたり、見当違いなリソースを調べていたりする。

原因はシンプルです。DevOps Agent に「自社の運用知識」を教えていないからです。この記事では、カスタムスキル（SKILL.md）の書き方から登録方法、そして書いて終わりにしない運用サイクルまでを、実際のEC2 CPU高負荷対応スキルを例に解説します。

この記事で分かること

• DevOps Agent のスキル体系（カスタムスキル・学習済みスキル）の全体像
• SKILL.md のファイル構成と frontmatter の書き方
• EC2 CPU高負荷を題材にしたカスタムスキルの実例
• SKILL.md を書くときに押さえておくべき5つのポイント
• 「書いて終わり」にしない運用サイクルの回し方

関連記事 CloudWatchアラームから3分で自動調査開始 — DevOps Agent × EventBridge構成パターン DevOps Agent の基本構成（CloudWatch → EventBridge → Agent）はこちらで解説しています。

スキルの全体像（カスタムと学習済みの2系統）

DevOps Agent のスキルは大きく2系統に分かれます。

カスタムスキル は、自社の運用知識を SKILL.md ファイルとして記述し、DevOps Agent に読み込ませる仕組みです。「この障害にはこのログを見て、このメトリクスを確認して、この手順で対処する」という調査・修復の手順書を、Agent が理解できる形で渡します。

学習済みスキル は、DevOps Agent が Agent Space のデータから自動生成するナレッジです。現時点では4種類あります。

学習済みスキル	内容	更新タイミング
Agent Space Understanding	AWS アカウント・リソース・依存関係のマップ	構成変更時 + 3日ごと
Understanding Code Dependencies	サービス間・パッケージ間の依存関係	構成変更時 + 定期更新
Understanding Pipeline Topology	CI/CD パイプラインの構成マップ	構成変更時 + 定期更新
Tool Use Best Practices	過去の調査から抽出したツール使用パターン	30回の調査ごと

学習済みスキルは「環境を理解する」ためのもの、カスタムスキルは「対処方法を教える」ためのもの、と考えると整理しやすいです。まず環境の理解は Agent に任せて、自分たちは対処方法のスキルを書くことに集中する——これが効率的な役割分担です。

SKILL.md のファイル構成

カスタムスキルの実体は、特定のディレクトリ構成を持つファイル群です。

ec2-high-cpu-investigation/
├── SKILL.md              # 必須：スキル本体（Markdown）
├── references/           # 任意：補足資料
│   └── ec2-metrics-thresholds.md
└── assets/               # 任意：画像・データファイル
    └── investigation-flow.png

SKILL.md だけが必須で、references/ と assets/ はオプションです。この構成は Agent Skills 仕様（agentskills.io）のサブセットで、実行可能なスクリプト（scripts/ ディレクトリ）は将来のために予約されていますが、現時点では非対応です。

frontmatter（Agent がスキルを選ぶ判断基準）

SKILL.md の冒頭には、YAML の frontmatter ブロックを記述します。

---
name: ec2-high-cpu-investigation
description: Investigation procedures for EC2 instances with sustained high
  CPU utilization. Use this skill when CloudWatch CPUUtilization alarms fire,
  when users report application slowness traced to EC2, or when auto-scaling
  events indicate persistent compute pressure.
---

name はスキルの一意識別子で、小文字・数字・ハイフンのみ、最大64文字。ハイフンで開始・終了はできません。

description は Agent がスキルを使うかどうかを判断する最も重要なフィールドです。ここが曖昧だと、関連する調査でもスキルがスキップされてしまう。「いつ・なぜ・どんな症状のときに使うか」を Agent の視点で具体的に書くのがポイントです。

悪い例と良い例を比較します。

# 悪い例：抽象的すぎて Agent が判断できない
description: EC2 skill

# 良い例：症状・サービス・トリガー条件を明示
description: Investigation procedures for EC2 instances with sustained high
  CPU utilization. Use this skill when CloudWatch CPUUtilization alarms fire,
  when users report application slowness traced to EC2, or when auto-scaling
  events indicate persistent compute pressure.

ひとつ注意点があります。description は 英語で書くことを推奨 します。日本語で入力するとエラーになるケースが報告されています（2026年6月時点）。name も英語のみ対応です。SKILL.md 本文の手順部分は日本語でも動作しますが、frontmatter は英語で統一しておくのが安全です。

手順セクション（ステップバイステップで書く）

frontmatter の後に、実際の調査手順を Markdown で記述します。ここで大事なのは、宣言的な説明ではなくステップバイステップの手順で書く ことです。

# Declarative (bad example)
If CPU usage is high, check processes and identify the root cause.

# Step-by-step (good example)
## Step 1: Check CPUUtilization trends
Query CloudWatch for CPUUtilization over the past hour.
If above 80% for more than 15 minutes, proceed to Step 2.
If it is a temporary spike, check deployment history.

## Step 2: Identify top CPU consumers
Use SSM Run Command to execute `top -bn1 -o %CPU | head -20`.
Record the top 3 process names and their CPU%.

Agent は「次に何をすべきか」が明確なほど、精度の高い調査を行います。分岐条件（「〜の場合は Step X に進む」）も積極的に書いてみてください。

references/ と assets/ の使い分け

SKILL.md が長くなりすぎる場合は、補足情報を references/ に分離します。

references/
└── ec2-metrics-thresholds.md    # メトリクスの閾値一覧

Agent は SKILL.md を先に読み、必要に応じて references/ のファイルを参照します。SKILL.md は500行以下、5,000トークン以下 に収めるのが推奨されています。閾値テーブルや詳細な設定リファレンスは references/ に逃がして、SKILL.md 本体は手順に集中させます。

assets/ には画像やデータファイルを配置できます。アーキテクチャ図やフローチャートを含めると、Agent の環境理解が向上します。

実践 — EC2 CPU高負荷の対応スキルを書いてみる

ここからは実際に、EC2 の CPU 高負荷アラームに対応するカスタムスキルを書いてみます。

その前に、DevOps Agent の エージェントタイプ を押さえておきます。スキルは特定のタイプに割り当てることで、必要な場面でだけ読み込まれるようになります。

エージェントタイプ	役割	割り当てるスキル
Incident Triage	初期トリアージ・優先度判定	フィルタリングスキル
Incident RCA	根本原因分析	調査スキル
Incident Mitigation	自動インシデントレスポンス	修復スキル
On-demand	会話型クエリ	汎用スキル
Evaluation	プロアクティブな改善提案	評価スキル
Generic	全タイプで利用可能（デフォルト）	—

これを踏まえて、参考程度に Incident RCA 向けと Incident Mitigation 向けの2つのスキルを書いていきます。

Incident RCA 向けスキル（根本原因分析）

まずは「何が起きているかを調べる」根本原因分析のスキルです。

---
name: ec2-high-cpu-investigation
description: Investigation procedures for EC2 instances with sustained high
  CPU utilization above 80%. Use this skill when CloudWatch CPUUtilization
  alarms fire, when application response times degrade, or when Auto Scaling
  events indicate persistent compute pressure. Covers single-instance and
  ASG scenarios.
---

# EC2 High CPU Investigation

## Step 1: Confirm the alarm and identify the instance

Retrieve the CloudWatch alarm details to confirm:
- Which EC2 instance(s) triggered the alarm
- The current CPUUtilization value
- How long CPU has been above the threshold
- Whether the instance is part of an Auto Scaling Group

If the instance is in an ASG, also check whether scaling actions
have been triggered and whether they succeeded.

## Step 2: Analyze CPU trends

Query CloudWatch for CPUUtilization over the past 6 hours with
5-minute granularity. Classify the pattern:
- **Sudden spike**: Check for recent deployments or cron jobs
- **Gradual increase**: Check for memory leaks or connection growth
- **Sustained plateau**: Check for under-provisioned instance type

Also check these related metrics:
- NetworkIn/NetworkOut (traffic spike?)
- StatusCheckFailed (hardware issue?)
- EBSWriteOps/EBSReadOps (I/O bottleneck?)

## Step 3: Identify the top CPU consumers

Use SSM integration (via custom MCP server or SSM Automation runbook)
to execute on the instance:
- `top -bn1 -o %CPU | head -20` for process-level CPU usage
- `ps aux --sort=-%cpu | head -10` for detailed process info
- `uptime` for load average trend

If SSM is not configured, note this limitation in the report
and recommend enabling SSM Agent.

## Step 4: Check recent changes

Review the following for changes in the past 24 hours:
- Deployment history from the connected CI/CD pipeline
- CloudTrail events for the instance (RunInstances,
  ModifyInstanceAttribute, CreateImage)
- Auto Scaling activities (scaling events, launch failures)

## Step 5: Summarize findings

Provide a summary with:
1. Current status: healthy / degraded / critical
2. Root cause hypothesis with supporting evidence
3. Recommended actions ranked by priority:
   - Immediate: kill runaway process, scale out ASG
   - Short-term: right-size instance, optimize application
   - Long-term: implement auto-scaling policies

ポイントは、各ステップで 何を確認し、結果をどう解釈するか まで書いていることです。「CPU を確認する」だけでなく、「急上昇ならデプロイ履歴を見る」「漸増ならメモリリークを疑う」という判断基準を含めると、Agent の調査精度が大きく変わります。

Incident Mitigation 向けスキル（自動インシデントレスポンス）

調査の次は修復です。修復スキルは Incident RCA 向けとは別に作成し、単一目的で小さく 保ちます。

---
name: ec2-high-cpu-remediation
description: Remediation procedures for EC2 high CPU issues. Use after
  ec2-high-cpu-investigation identifies the root cause. Covers process
  restart, instance type change recommendations, and ASG scaling adjustments.
---

# EC2 High CPU Remediation

## When to use this skill

Apply after investigation confirms one of these root causes:
- Runaway application process
- Under-provisioned instance type
- Missing or misconfigured Auto Scaling policy

## Remediation: Runaway process

If a specific process is consuming excessive CPU:
1. Identify the process name and PID from the investigation report
2. Check if the process is safe to restart (not a critical system process)
3. Create a PR to add a health check or watchdog for the process
4. Document the process restart procedure in the PR description

## Remediation: Under-provisioned instance

If sustained CPU indicates the instance type is too small:
1. Recommend the next instance type based on current usage pattern
   - Compute-intensive: suggest c-family instances
   - General purpose: suggest m-family instances
2. Create a PR updating the IaC definition with the recommended type
3. Include cost comparison in the PR description

## Remediation: Auto Scaling misconfiguration

If the ASG exists but did not scale:
1. Check the scaling policy thresholds and cooldown periods
2. Verify the max capacity allows additional instances
3. Create a PR adjusting the scaling policy parameters

このように調査スキルは Incident RCA に、修復スキルは Incident Mitigation に割り当てることで、Agent が不要なスキルを読み込まなくなり、コンテキスト消費を抑えられます。

関連記事 DevOps Agent × MCP × GitHubで障害修復PRを自動作成 — Runbookの落とし穴も解説 修復スキルで生成したPRを GitHub に自動作成する構成はこちらで解説しています。

SKILL.md を書くときの5つのポイント

スキルを書いていく中で気づいた、押さえておくべきポイントを5つ整理します。

【1】description に全力を注ぐ

SKILL.md の本文がどれだけ丁寧に書かれていても、description が曖昧だと Agent はそのスキルを選んでくれません。「どんな症状のとき」「どのサービスで」「どんなアラームが鳴ったとき」に使うかを、英語で具体的に書いておくのが大切です。文字数は最低100文字、最大1,024文字。

【2】1スキル1目的

「EC2 の CPU も見て、RDS の接続数も見て、ECS のメモリも見る」という万能スキルは避けた方が無難です。Agent の判断精度が下がり、コンテキストも圧迫してしまう。1つのスキルは1つの障害パターンに絞り、複数のスキルを組み合わせて使うのがおすすめです。

【3】サイズ制限を意識する

制限項目	値	種別
ZIP ファイル全体	6 MB	ハードリミット
ファイル数	100	ハードリミット
SKILL.md 行数	500行以下	推奨設計値
SKILL.md トークン数	5,000トークン以下	推奨設計値

ZIP サイズとファイル数はシステム上の制限で、超えるとアップロードが拒否されます。一方、SKILL.md の行数・トークン数はパフォーマンスを確保するための設計ガイドラインで、Agent Skills 仕様のベストプラクティスに由来します。超えても登録はできますが、Agent の精度や応答速度に影響が出る可能性があります。

SKILL.md が膨大になるときは、閾値テーブルやメトリクスリファレンスを references/ に分離します。Agent は必要に応じて references/ を参照するので、SKILL.md 本体は手順に集中させます。

【4】frontmatter は英語で書く

name と description は英語のみ対応です。日本語を入力するとバリデーションエラーになる場合があります（2026年6月時点）。SKILL.md 本文の手順は日本語でも動作しますが、frontmatter は英語で統一しておくのが確実です。

【5】エージェントタイプを指定する

デフォルトの Generic（全タイプ共通）のままにせず、スキルの用途に合ったエージェントタイプを指定しておくと効果的です。調査スキルなら Incident RCA、修復スキルなら Incident Mitigation、トリアージ用のフィルタリングスキルなら Incident Triage。コンテキスト消費が減り、Agent の判断精度が上がります。

登録方法とプライベートリポジトリの注意点

カスタムスキルの登録方法は主に4つあります。

方法	向いているケース
UI で作成	手軽に試したいとき。SKILL.md 単体のスキル
ZIP アップロード	references/ や assets/ を含むスキル
GitHub リポジトリからインポート	バージョン管理したいとき。チーム運用向き
AWS CLI / SDK	CI/CDパイプラインに組み込みたいとき

運用が本格化したら GitHub リポジトリからインポート がおすすめです。スキルを Git 管理でき、変更履歴が残り、Operator Web App の「Sync」ボタンで最新版に同期できます。

ただし、プライベートリポジトリからのインポートには注意が必要です。

Agent Space に紐づいた GitHub アカウントが、パイプライン連携（Capabilities → Pipeline → GitHub） で接続されている必要があります。GitHub MCP Server の認証とは別系統です。MCP Server でPR作成ができていても、パイプライン連携が未設定ならプライベートリポジトリからのスキルインポートは失敗します。

GitHub連携の認証チャネル（2つは独立）

パイプライン連携 → スキルインポート、コードコンテキスト参照
MCP Server      → PR作成、Issue操作、コード検索

この2つは完全に独立しています。両方を設定しておかないと、「PR は自動で作れるのに、スキルはインポートできない」という状態になります（前回の記事でこの落とし穴に実際にハマりました）。

スキルを育てる運用サイクル

カスタムスキルは「一度書いて終わり」ではありません。調査結果を見ながら改善し続けることで、Agent の精度が上がっていきます。

調査レポートからフィードバックを拾う

DevOps Agent の調査レポートには、Agent がどのスキルを使ったか、どの手順を実行したかが記録されます。レポートを読むときは、次の観点でチェックします。

• スキルが発火しなかった → description が曖昧。症状やサービス名を追記する
• 手順の途中で止まっている → 前提条件が不足。SSM 未設定ならフォールバック手順を追加する
• 見当違いのリソースを調べている → Step の分岐条件を追加する
• レポートに欲しい情報が足りない → Step の最後の「Summarize findings」に項目を追加する

この改善ループを月1回でも回すだけで、スキルの精度は着実に上がっていきます。

学習済みスキルとカスタムスキルの棲み分け

「Agent が自動で学習するなら、カスタムスキルを書く必要はないのでは？」と思うかもしれません。

結論から言うと、両方必要 です。

学習済みスキルが学ぶのは「環境構成」と「ツールの使い方」。どのアカウントにどんなリソースがあるか、CloudWatch Logs Insights のクエリはどう書くと効率的か——環境の「地図」と「道具の使い方」を自動で覚えてくれる存在です。

一方、カスタムスキルが担うのは「対処方法」。「CPU が高騰したらまず何を見るか」「このサービスではどのプロセスが暴走しやすいか」「修復 PR はどんなテンプレートで出すか」。環境データからは学習できない、運用チームの暗黙知がここに入ります。

領域	学習済みスキル	カスタムスキル
環境構成の理解	自動で学習	書く必要なし
ツール使用パターン	30回の調査ごとに学習	書く必要なし
障害の調査手順	学習しない	自分で書く
修復手順	学習しない	自分で書く
トリアージ基準	学習しない	自分で書く

学習済みスキルは Operator Web App の Knowledge → Skills タブで確認でき、不要なら個別に無効化もできます。Tool Use Best Practices は30回の調査ごとに自動更新されるので、Agent を使い込むほど精度が上がる仕組みです。

バージョン管理と GitHub 連携

スキルを GitHub リポジトリで管理すると、次のワークフローが回せます。

1. ローカルで SKILL.md を編集
2. PR を出してチームレビュー
3. main にマージ
4. Operator Web App で「Sync」を押して反映

スキルの変更も通常のコード変更と同じフローに乗るため、「誰がいつ何を変えたか」が追跡できます。Sync 時にはリポジトリの最新状態で丸ごと置き換わるため、Operator Web App 側でのローカル編集は上書きされる点に注意してください（ステータスとエージェントタイプの設定は保持されます）。

コストへの影響

カスタムスキルの登録・参照自体は 無料 です。

コストに影響するのは、スキルを読み込むことで Agent の調査時間が変化する部分。適切なスキルがあれば無駄な推論ステップが減り、結果的に調査時間が短縮されてコストが下がる場合もあります。

逆に、不要なスキルを大量に Active にしておくと、Agent が毎回すべてのスキルの description を評価するため、コンテキスト消費が増えてしまう。使わなくなったスキルは削除ではなく Inactive に切り替えておくと、いつでも復活できて安心です。

まとめ

DevOps Agent のカスタムスキルは、Agent の調査精度を自社環境に最適化するための仕組みです。SKILL.md の構造自体はシンプルで、frontmatter に name と description を書き、本文にステップバイステップの手順を記述するだけ。ただし、description の質が Agent の判断精度を左右するため、ここだけは手を抜けません。

全ての障害パターンをカバーしようとすると手が止まります。まずは自社で頻発する障害の上位3つに絞ってスキルを書き、調査レポートを見ながら月1回の改善サイクルを回すところから始めてみてください。

参考文献

• DevOps Agent Skills — AWS 公式ドキュメント — スキルの仕様・作成手順・制限事項の公式リファレンス
• Learned Skills — AWS 公式ドキュメント — 学習済みスキル4種類の詳細
• Best Practices for Deploying AWS DevOps Agent in Production — AWS Blog — 本番環境でのデプロイベストプラクティス
• Extend AWS DevOps Agent with custom skills — AWS Builder Center — カスタムスキル拡張の公式チュートリアル
• sample-code-for-devops-agent-skills — GitHub — AWS 公式のサンプルスキル集
• AWS DevOps Agentのスキル機能を試してみた — サーバーワークスエンジニアブログ — カスタムスキルと学習済みスキルの検証レポート
• AWS DevOps Agent にスキルを登録して調査を試すメモ — スキル登録の実践メモ
• AWS DevOps Agent 10 best practices — DEV Community — 運用ベストプラクティス10選