良いAgent Skillsの作り方完全解説!AI活用のプロがSkillsを作るコツを話します

概要

AIプログラミング塾のいまにゅ氏が、Claude CodeやCodexなどで使う「Agent Skills」を高品質に作るための考え方を解説。SKILL.mdを書き始める前の要件定義こそが品質を左右するという主張を軸に、具体的な設計項目や運用のコツを紹介している。

主なポイント

• 良いスキル作りはSKILL.mdを書く前の要件定義(目的・対象範囲・入力・出力・制約ルール・完成条件の6項目)を明確にすることで決まる
• スキルはAIエージェント向けの手順書であり、人間向けの長い説明文ではなく箇条書きで簡潔に書くべき
• 要件定義にはMatt Pocock作の「Grill Me」スキルを使い、AIとの壁打ちで曖昧な点を掘り下げてもらうと精度が上がる
• スキルの自動発動可否はSKILL.mdのdescription(説明文)で決まるため、発動条件と非発動条件を明記する
• Claude Code/Codexのような都度目的を決めて使うツールは明示的にスキルを呼び出し、Slack常駐AIエージェントのような秘書役には自動発動する設計が向く
• 1スキル=1つのまとまった業務単位にし、詰め込みすぎない(逆に細分化しすぎも避ける)
• 完成条件は点数化・チェックリスト化(例: 100項目中80点以上で合格)すると、AIが迷わず終着点を判断できる
• 詳細情報はreferenceフォルダのMarkdownに分離し、繰り返し使う決定的処理はscriptsフォルダに入れて、SKILL.mdは核となる手順のみに絞る
• 失敗コストが高い作業は手順・順序を固定し確認ポイントや禁止事項を明記、逆にやり直しが容易な作業はゴールだけ示してAIの柔軟性を活かす
• 出力を見てフィードバックし、それを基準としてスキルに反映する反復改善(セルフリファイン)を繰り返すことで精度が上がる

実践に使えること

• 新しいスキルを作る前に、目的・対象範囲・入力・出力・制約・完成条件の6項目を先に言語化してからSKILL.mdを書く
• 要件が曖昧なまま「なんとなくこんな感じで」と指示せず、壁打り系スキル(Grill Meなど)を使って質問形式で要件を掘り下げる
• SKILL.mdの説明文(description)に「いつ発動すべきか」「いつ発動すべきでないか」を明記し、自動発動の精度を上げる
• 完成基準をチェックリストや点数制にして、サブエージェントに自己評価させる仕組みを組み込む
• 詳細ルールやフォーマット基準はSKILL.md本体でなくreferenceフォルダのMarkdownに分離して肥大化を防ぐ
• スキルの出力を確認→フィードバック→基準化→再生成のサイクルを回し、都度スキルの完成度を上げていく