ゆら先輩、AIに毎回同じ仕事を頼むたびに、長い説明を書き直すのが大変です……。
ソーニャAgent Skillsを使うと、仕事の目的・手順・品質基準をAIが再利用できる形に整理できますよ。
ゆらSkillって、詳しい人だけが作れる特別な設定なのでしょうか？
ソーニャ最初に用意する情報は4つだけです。この記事で、初心者がSkillを設計して検証する流れを学べます。
Agent Skillsは、AIに繰り返し仕事を依頼するときの「目的・手順・判断基準・検証方法」をまとめて再利用する仕組みです。Claude CodeやCodexで、文章作成、Web制作、調査、アプリ開発などの作業品質を安定させるために使えます。
この記事では、Agent Skillsの考え方から、SKILL.mdの設計、評価、改善までを一つの講座として整理します。読了後は、自分の仕事をAIが再現できるSkillへ変換するための設計図を作れるようになります。
この記事で学べること
- Agent Skillsが担う役割と、強いSkillの条件
- 初心者が最初に整理する4つの情報
- コピペで使えるSkill作成プロンプト
- 意図の整理から検証まで進める12ステップ
- 8層設計、発火評価、出力評価、修復ループ
Agent Skillsは小さな業務システム
Skillは、AIへ毎回同じ説明を送るための長い文章です。仕事の目的、入力、出力、成功条件、失敗パターン、検証方法をまとめ、AIが同じ手順を繰り返せる状態を作ります。
強いSkillには、次の仕組みがあります。
- 情報が足りないときに、先に質問する
- 成果物を検証してから完了を報告する
- 失敗した箇所を記録し、次の作業へ活かす
- 同じ修正を繰り返すとき、方針を見直す
- 人間の承認が必要な操作を明確に止める
Skillの価値は、AIの能力を引き出す業務の型にあります。
初心者が最初に用意する4つの情報
Skill設計の入口で、次の4つを整理します。
- どんな作業を繰り返しているか
- どんな状態になれば成功か
- どんな失敗を避けたいか
- 理想に近い参考例があるか
たとえば「ブログ記事作成Skill」なら、次のように書けます。
| 項目 | 例 |
|---|---|
| 繰り返す作業 | 素材を読み、初心者向けの記事に整える |
| 成功条件 | 読者が元資料を読まずに内容を理解できる |
| 避けたい失敗 | 事実の追加、重複、AIらしい抽象表現 |
| 参考例 | 自分が過去に書いた記事、理想のブログ |
この4つがあれば、AIに不足情報を質問させ、ファイル構成や検証方法まで設計させられます。
そのまま使えるSkill作成プロンプト
Claude CodeまたはCodexに、次のプロンプトを貼り付けます。[ ]の部分を自分の内容へ置き換えてください。
あなたはAgent Skills Architect、Workflow Engineer、Evaluator Designerです。
私はAgent Skills制作の初心者です。
専門用語やファイル構成を理解していなくても、Claude CodeまたはCodexで使える完成済みSkillを設計してください。
利用可能なファイル操作ツールがあれば、Skillフォルダと必要ファイルも作成してください。
■ 作りたいSkill
作業内容：[一文で書く]
利用環境：[Codex／Claude Code／両方／分からない]
実現したいこと：[分かる範囲で書く]
依頼例：[1〜3個]
避けたい失敗：[絶対に避けたいこと]
参考例：[あれば記載。なければ「なし」]
品質レベル：[簡易／実務品質／最高品質／分からない]
■ 初心者対応
情報が不足している場合は、最初に最大7問をまとめて質問してください。
「分からない」「おまかせ」と答えた項目は、3案を示して推奨案を選んでください。
作業を進められる項目は既定値を採用し、assumptions.mdに記録してください。
専門用語には一行の説明を付けてください。
公開、課金、デプロイ、データ削除、認証情報の変更は、人間の承認なしに実行しないでください。
■ 必須成果物
brief.md、acceptance-criteria.md、assumptions.md、SKILL.md、検証用ファイルを作成してください。
発火条件、入力、出力、成功条件、失敗パターン、検証方法、修復ループ、終了条件を設計してください。
最後に、実行した検証コマンドと結果を報告してください。最初はSkillの目的を一文で書けば始められます。 設計と検証はAIに段階的に進めさせます。
Skillを設計する12ステップ
STEP 1〜3：意図、発火条件、ルールを整理する
曖昧な依頼を、目的、対象ユーザー、入力、出力、成功条件、絶対条件、対象外の作業、想定失敗へ変換します。brief.md、acceptance-criteria.md、assumptions.mdへ記録します。
次に、Skillを使う依頼と対象外の依頼をdescriptionへ書きます。Skill名を直接呼ばれなくても、目的や作業内容から発火できる表現を含めます。
ルールは3段階に分けます。
- HARD GATES：必ず守る条件。違反したら不合格にする
- DEFAULTS：通常時に採用する既定値
- PREFERENCES：品質を高めるための好み
STEP 4〜5：ファイル構造とSKILL.mdを作る
skill-name/
├── SKILL.md
├── USAGE.md
├── references/
│ ├── domain-knowledge.md
│ ├── quality-rubric.md
│ └── failure-patterns.md
├── evals/
│ ├── trigger-evals.json
│ └── output-evals.json
└── scripts/SKILL.mdにはMission、When to use、When not to use、Inputs、Workflow、Hard gates、Quality rubric、Verification、Repair loop、Stop conditions、Completion reportを置きます。長い知識や参考例はreferences/へ分けます。
STEP 6〜8：改善ループと検証を組み込む
作業を次の順番で回します。
PLAN → BUILD → RUN → OBSERVE → GRADE → REPAIR → RETEST → STOP複雑な成果物では、作る役と採点する役を分けます。Webならブラウザで操作し、アプリならUI・API・保存状態を確認します。
ファイル存在、JSONの妥当性、禁止文字列、型エラー、リンク切れのような機械的な確認は、スクリプトで判定します。--helpを用意し、破壊的な処理には--dry-runを付けます。
STEP 9〜12：評価、修復、完成報告
trigger-evals.jsonへ、発火すべき依頼と対象外の近い依頼をそれぞれ8〜10件入れます。口語、短文、長文、誤字、Skill名を出さない表現も含めます。
output-evals.jsonへ、通常ケース、曖昧ケース、境界ケースを最低3件用意します。主観品質を比べるときは、旧版と新版を隠したブラインド比較が有効です。
失敗をTrigger、Context、Procedure、Tool、Verification、Evaluator、Stop condition、Memoryのどこに分類できるか考えます。改善は最大3回を目安に進め、最も評価が高いチェックポイントを採用します。
完成報告には、Skill名、保存場所、できること、発火例、対象外の例、検証コマンド、検証結果、残っている制約を含めます。
Skillを8層で設計する
12ステップは、実行時の役割として次の8層に整理できます。
- Trigger Router：使うべき依頼を見分ける
- Intent Compiler：曖昧な依頼を作業契約へ変える
- Context Loader：必要な知識だけを読み込む
- Rule Compiler：ルールを検査可能な条件へ変える
- Maker：成果物を作る
- Checker：別の視点で評価する
- Repair Loop：失敗箇所を修正して再検証する
- Durable Memory：知見と状態を次回へ残す
設計時は12ステップ、実行時は8層というように使い分けると、Skill全体の役割が見えやすくなります。
Claude CodeとCodexで共有できる設計
両方の環境で使うSkillは、共通のSKILL.mdを中核にします。保存場所と呼び出し方は環境ごとに確認します。
| 項目 | Claude Code | Codex |
|---|---|---|
| プロジェクト用 | .claude/skills/skill-name/ | .agents/skills/skill-name/ |
| 全体共通 | ~/.claude/skills/skill-name/ | ~/.agents/skills/skill-name/ |
| 呼び出し | /skill-name | $skill-name |
Skill名は小文字・数字・ハイフンで統一し、フォルダ名とname:の値を完全に一致させます。
SKILL.mdの基本テンプレート
name: your-skill-name
description: >
Use this skill when the user wants [目的] and the task requires
[専門工程・検証・対象形式]. Use it for [代表例].
Do not use it for [対象外の作業].
compatibility: Designed for Codex and Claude Code compatible Agent Skills clients.
metadata:
version: "1.0.0"Mission
Primary user: [対象]
Main outcome: [成果]
Main risk to prevent: [失敗]
Instruction priority
HARD GATES > Acceptance criteria > Defaults > Preferences
Workflow
Compile → Inspect → Plan → Build → Run → Verify → Repair → Retest → Stop
Hard gates
- [絶対条件]
- 検証前に完成報告をしない
- 失敗した検証結果を合格として報告しない
- 承認が必要な操作を自動実行しない今日から始める実践チェックリスト
- [ ] 繰り返している作業を一文で書く
- [ ] 成功条件を具体的な状態で書く
- [ ] 避けたい失敗を3つ書く
- [ ] 理想に近い参考例を1つ選ぶ
- [ ] Skill作成プロンプトをAIへ渡す
- [ ]
SKILL.mdと検証ファイルを確認する - [ ] 実際の依頼で発火と出力を試す
- [ ] 失敗例を評価ファイルへ追加する
まとめ
Agent Skillsは、AIへ仕事の型を渡す仕組みです。設計の入口で必要な情報は、繰り返す作業、成功条件、避けたい失敗、参考例の4つです。
その情報をもとに、AIへ意図の整理、発火条件、工程、評価、修復ループ、記憶の保存まで設計させます。今日の作業を一文で書くことが、あなた専用のSkillを作る最初の一歩です。
*参考：@ai_ai_ailover氏のX投稿をもとに再構成*
