How to Create 'Agent Skills' Known Only to Top Global Practitioners

Claude／Codex対応・初心者がコピペするだけで動けるSkill作成プロンプト付き完全版

Agent Skillsを作ってみたい。

でも、いざClaudeやCodexを開くと、最初の一言で止まる。

「何を指示すればいいのか分からない」

「SKILL.mdに何を書けばいいのか分からない」

「ルールをたくさん書いても、本当に守ってくれるのか不安」

「そもそも、どこまで自分で仕様を考えなければいけないのか分からない」

これは当然だ。

初心者がSkillを作る時に、最初からYAML、評価指標、発火条件、検証スクリプト、サブエージェント設計まで考える必要はない。

必要なのは、たった四つである。

1. 何を繰り返しやっているか
2. どうなったら成功か
3. どんな失敗だけは避けたいか
4. 理想に近い参考例があるか

残りは、ClaudeやCodexに「Skill設計者」として考えさせればいい。

2026年7月時点で、CodexとClaude Codeはいずれも、SKILL.mdを中心に、必要に応じてスクリプト、参考資料、テンプレートなどを読み込むAgent Skillsの仕組みを採用している。CodexではSkillの名前と説明を最初に見て、必要だと判断した時だけ本文を読む。Claude Codeも同様に、Skillの本文は使用時に読み込まれる。つまり、重要なのは長大なプロンプトを作ることではなく、発火条件、工程、検証方法、終了条件を設計することだ。

まずは、以下のプロンプトをそのまま使ってほしい。

第1章　初心者用・完全Skill作成プロンプト

以下をClaude CodeまたはCodexの通常チャットに貼り付ける。

Codexでは、先に$skill-creatorを呼び出してから貼ってもよい。Codex公式のSkill Creatorも「何をするSkillか」「いつ発火するか」「スクリプトを含めるか」を確認するが、以下のプロンプトは、そこへ品質評価とループエンジニアリングまで追加した完全版である。

あなたは、世界最高水準の

「Agent Skills Architect」

「Workflow Engineer」

「Evaluator Designer」

です。

私はAgent Skills制作の初心者です。

私が専門用語やファイル構成を理解していなくても、

Claude CodeまたはCodexで実際に使用できる完成済みSkillを作ってください。

説明だけで終了せず、利用可能なファイル操作ツールがある場合は、

実際にSkillフォルダと必要ファイルを作成してください。

ファイルを作成できない環境の場合は、

ファイル名ごとに完全な内容を、省略せず出力してください。

━━━━━━━━━━━━━━━━━━

■ 私が作りたいSkill

━━━━━━━━━━━━━━━━━━

作りたいSkill：

【ここに一文で書く】

利用環境：

【Codex／Claude Code／両方／分からない】

このSkillを使って実現したいこと：

【分かる範囲で書く。分からなければ「おまかせ」】

実際に頼みそうな依頼例：

【1〜3個。分からなければ「おまかせ」】

絶対に避けたい失敗：

【例：文章がAIっぽい、デザインがテンプレっぽい、

ボタンが見た目だけで動かない、テストせず完成と言う、など】

理想に近い参考例、資料、Webサイト、文章、コード：

【あれば記載。なければ「なし」】

品質レベル：

【簡易／実務品質／最高品質／分からない】

分からない項目：

【すべて、おまかせで補完してよい】

━━━━━━━━━━━━━━━━━━

■ 初心者対応ルール

━━━━━━━━━━━━━━━━━━

1. 情報が不足している場合は、最初に最大7問まで、 一度にまとめて質問してください。

1. 私が「分からない」「おまかせ」と答えた項目は、 選択肢を3案出し、その中から最も再現性の高い案を推奨してください。

1. 私が回答しなくても作業を進められる項目は、 妥当な既定値を採用し、assumptions.mdに仮定として記録してください。

1. 専門用語を使う場合は、 初心者にも分かる一行説明を括弧内に付けてください。

1. 課金、公開、デプロイ、データ削除、認証情報の変更など、 取り返しのつかない操作は自動実行しないでください。

1. 仕様が変化しやすいサービス、API、ライブラリを扱う場合は、 現在の公式ドキュメントを確認してください。 古い記憶だけで仕様を決めないでください。

━━━━━━━━━━━━━━━━━━

■ Skill設計の必須工程

━━━━━━━━━━━━━━━━━━

次の順番を必ず守ってください。

STEP 1：意図のコンパイル

私の曖昧な依頼を、以下へ変換してください。

• Skillの目的
• 対象ユーザー
• 入力
• 出力
• 成功条件
• 絶対条件
• 今回やらないこと
• 想定される失敗
• 必要なツール
• 人間の承認が必要な操作

以下を作成してください。

• brief.md
• acceptance-criteria.md
• assumptions.md

STEP 2：発火条件の設計

Skillが「使うべき時」と「使わない時」を明確にしてください。

descriptionには次を含めてください。

• Skillが何をするか
• どんなユーザー目的で使うか
• ユーザーがSkill名を言わなくても発火すべき状況
• 似ているが発火してはいけない依頼
• 重要な対象ファイル、形式、作業名

descriptionは簡潔にし、重要な用途を先頭へ置いてください。

単に「高品質にします」「役立ちます」と書かないでください。

STEP 3：ルールの優先順位付け

すべての指示を、次の3段階に分けてください。

A. HARD GATES

絶対に破ってはいけない条件。

違反したら成果物全体を不合格にする。

B. DEFAULTS

基本的には従う既定値。

プロジェクト上の明確な理由があれば変更可能。

C. PREFERENCES

より良くするための好み。

HARD GATESとDEFAULTSを満たした後に最適化する。

「MUST」「絶対」「高品質」と書くだけでなく、

可能なものはテスト、コマンド、JSON判定、チェック項目へ変換してください。

STEP 4：Skill構造の設計

原則として、以下を検討してください。

<skill-name>/

├── SKILL.md

├── USAGE.md

├── references/

│ ├── domain-knowledge.md

│ ├── quality-rubric.md

│ └── failure-patterns.md

├── templates/

│ ├── brief-template.md

│ └── scorecard-template.json

├── evals/

│ ├── trigger-evals.json

│ └── output-evals.json

└── scripts/

└── 必要な検証スクリプト

ただし、不要なファイルは作らないでください。

SKILL.mdには毎回必要な中核工程だけを書いてください。

詳細な知識、長い例、API仕様、スタイルガイドはreferencesへ分離してください。

各referenceについて、

「いつ読むのか」

「何を判断するために読むのか」

をSKILL.mdに明記してください。

同じ決定的処理を毎回AIが書き直す場合は、

scriptsへ移してください。

STEP 5：SKILL.mdの作成

SKILL.mdは、次の構成を基本にしてください。

• Mission
• When to use
• When not to use
• Inputs
• Required context
• Priority of instructions
• Workflow
• Hard gates
• Quality rubric
• Verification
• Repair loop
• Stop conditions
• Completion report
• Supporting files

Skill名は小文字、数字、ハイフンのみで作ってください。

フォルダ名とnameを一致させてください。

メインのSKILL.mdを巨大化させず、

原則500行未満、約5,000トークン未満を目安にしてください。

STEP 6：ループエンジニアリング

Skillを、一発生成で終了する手順にしないでください。

次のループを組み込んでください。

1. PLAN
2. BUILD
3. RUN
4. OBSERVE
5. GRADE
6. REPAIR
7. RETEST
8. STOP OR CONTINUE

ただし、簡単な作業に過剰なループを使わないでください。

初期値として最大3回まで反復してください。

次の場合は終了してください。

• HARD GATESをすべて通過した
• 合格点を超えた
• 直近2回で意味のある改善がない
• 同じ失敗を2回繰り返した
• コストや時間の上限に達した
• 人間の判断が必要になった

最後の版ではなく、

最も評価の高かったチェックポイントを採用してください。

STEP 7：生成役と評価役の分離

複雑または主観的な成果物では、

生成役と評価役を分けてください。

生成役：

成果物を作る。

評価役：

クリーンな文脈から成果物を確認し、

甘く採点せず、具体的な証拠を付ける。

評価結果には次を含めてください。

• criterion_id
• expected
• observed
• passed
• evidence
• severity
• likely_cause
• minimal_fix
• retest_method

評価役は、可能な場合、

ソースコードだけでなく実際の成果物を動かしてください。

Webならブラウザ操作、

アプリならUI・API・保存状態、

ゲームなら実プレイ、

動画なら時間軸とレンダー、

文章なら事実・声・感情曲線を確認してください。

STEP 8：検証スクリプト

機械的に判定できるものは、

LLMの感想ではなくスクリプトで検証してください。

例：

• ファイルの存在
• JSONの妥当性
• 禁止文字列
• ダミー実装
• 型エラー
• テスト結果
• リンク切れ
• 画像サイズ
• コントラスト
• テキストのオーバーフロー
• 出力形式
• 必須項目

スクリプトを作る場合は次を守ってください。

• 対話入力を要求しない
• --helpを用意する
• エラー原因と修正方法を表示する
• 可能ならJSONをstdoutへ出す
• 診断情報はstderrへ出す
• 再実行しても壊れない
• 破壊的操作には--dry-runを用意する
• 意味のある終了コードを返す

STEP 9：発火評価

trigger-evals.jsonに、最低でも次を作ってください。

• 発火すべき例：8〜10件
• 発火してはいけない近接例：8〜10件

表現を変えてください。

• 丁寧な依頼
• 口語
• 短文
• 長文
• 誤字を含む依頼
• Skill名を言わない依頼
• 複数工程に埋もれた依頼

明らかに無関係な例だけでなく、

キーワードは似ているが別Skillを使うべき例を含めてください。

STEP 10：出力評価

output-evals.jsonには最低3件を作ってください。

• 通常ケース
• 曖昧なケース
• 境界または失敗ケース

各ケースに以下を含めてください。

• prompt
• expected_output
• input_files
• assertions
• hard_gates
• human_review_points

可能なら、SkillありとSkillなし、

または旧版と新版を別のクリーンな文脈で比較してください。

主観品質は、どちらが新版かを隠してブラインド比較してください。

STEP 11：改善

評価結果をもとにSkillを最大3回改善してください。

改善時は、失敗例だけに効く特殊ルールを追加しないでください。

失敗の根本原因を次のどこかへ分類してください。

• Trigger
• Context
• Procedure
• Tool
• Verification
• Evaluator
• Stop condition
• Memory

指示を追加するだけでなく、

不要な指示の削除も検討してください。

STEP 12：完成報告

最後に初心者向けに、次を報告してください。

1. 作成したSkill名
2. 保存場所
3. フォルダ構成
4. このSkillができること
5. 発火する依頼例
6. 発火しない依頼例
7. 手動で呼び出す方法
8. 初回テスト方法
9. 検証結果
10. 残っている制約
11. 次回改善する場合に見るファイル

「完成しました」だけで終了せず、

実行した検証コマンドと証拠を示してください。

このプロンプトへ何を書けばいいのか

本当に一文だけでもよい。

たとえば、人間味のある日本語ライティングSkillを作りたいなら、こう書く。

作りたいSkill：

日本語のnote記事やX投稿を、人間が書いたような揺らぎと感情を残しながら作るSkill

利用環境：

Codex

このSkillを使って実現したいこと：

読みやすいが、AIっぽく整いすぎていない文章にしたい

実際に頼みそうな依頼例：

「この体験談をnote記事にして」

「この文章を私らしい言葉に直して」

絶対に避けたい失敗：

同じ語尾の連続、過剰な箇条書き、抽象論、嘘の体験談

理想に近い参考例：

自分の過去記事を後で渡す

品質レベル：

最高品質

ほかが分からなければ、末尾にこう書けばいい。

それ以外は分かりません。

初心者向けの最も安全で再現性の高い構成を選んでください。

この程度で、Skill設計は開始できる。

第2章　Skillを実際に保存し、呼び出す方法

Claude CodeとCodexでは、保存場所が少し異なる。

Codex

プロジェクト専用なら次の場所へ置く。

プロジェクト/

└── .agents/

└── skills/

└── skill-name/

└── SKILL.md

自分のすべてのプロジェクトで使うなら、次へ置く。

~/.agents/skills/skill-name/SKILL.md

Codexでは、プロンプト内でSkillを明示したり、CLIやIDEで$からSkillを選択したりできる。自動発火はdescriptionとの一致で決まる。

Claude Code

プロジェクト専用なら次の場所へ置く。

プロジェクト/

└── .claude/

└── skills/

└── skill-name/

└── SKILL.md

自分のすべてのプロジェクトで使うなら、次へ置く。

~/.claude/skills/skill-name/SKILL.md

Claude Codeでは、/skill-nameで手動実行できるほか、descriptionと依頼内容が合えば自動的に読み込まれる。

たとえばSkill名がhuman-japanese-writerなら、Claude Codeでは次のように呼び出す。

/human-japanese-writer

以下のメモをnote記事にしてください。

...

Codexでは次のように明示する。

$human-japanese-writer を使って、

以下のメモをnote記事にしてください。

...

最初のうちは自動発火だけに頼らず、明示的に呼び出した方が動作を確認しやすい。

第3章　Skillとは、長いプロンプトではない

強いSkillと弱いSkillの違いは、文章量ではない。

弱いSkillは、こう書く。

高品質なWebサイトを作ってください。

モダンで洗練されたデザインにしてください。

レスポンシブにしてください。

必ずテストしてください。

これでは「高品質」「モダン」「洗練」「テスト」の意味が曖昧だ。

一方、強いSkillはこう考える。

1. 誰に、どんな感情を与えるサイトか定義する
2. Visual Identityを決める
3. 2〜3個の異なるデザイン方向を比較する
4. 選定理由を記録する
5. 静的な完成レイアウトを作る
6. ブラウザで実際に操作する
7. 375px、768px、1440pxで確認する
8. デザイン品質、独自性、精度、機能性を別々に評価する
9. 失敗項目だけを直す
10. 最も評価の高い版を採用する

Skillの本質は、「正解を命令すること」ではない。

正解に近づく工程を、モデルが省略できないようにすることである。

第4章　海外の最前線で使われる八層設計

1．Trigger Router――いつ使うか

Skillは、中身より先に発火しなければ意味がない。

Agent Skillsでは、起動時にすべてのSkill本文を読むわけではない。最初は主にnameとdescriptionを見て、必要なSkillだけを読み込む。この仕組みはProgressive Disclosure、つまり「必要になった時だけ詳しい情報を開く設計」と呼ばれる。

だから、次のdescriptionは弱い。

description: Webサイト作成を支援します。

何をするのか、どんな時に使うのか、境界が分からない。

改善例はこうなる。

description: >

Use this skill when creating or redesigning production-quality websites

that require original visual direction, responsive implementation,

browser-based verification, accessibility checks, and iterative design

review. Use for landing pages, brand sites, product sites, portfolios,

and web applications where visual quality matters. Do not use for

backend-only work, tiny text edits, or isolated utility functions.

descriptionには、最低限「何をするか」と「いつ使うか」を入れる。Agent Skills仕様上、descriptionは最大1,024文字であり、Skill名は小文字、数字、ハイフンで作り、親フォルダ名と一致させる。

さらに、発火テストを作る。

公式のSkill作成ガイドでは、発火すべき依頼と発火すべきでない依頼をそれぞれ8〜10件程度作り、口語、誤字、暗黙表現、短文、長文を混ぜる方法が推奨されている。単に無関係な依頼を否定例にするのではなく、キーワードは似ているが別の仕事である「近接例」が重要だ。

2．Intent Compiler――曖昧な依頼を契約へ変える

非エンジニアが次のように頼んだとする。

おしゃれな予約アプリを作って。 使いやすくて、AIも入れて。

このまま実装を始めると、ほぼ確実にズレる。

まず、次へ変換する。

対象ユーザー：

小規模サロンのオーナーと顧客

最重要フロー：

顧客が空き枠を探し、予約し、確認メールを受け取る

AIの役割：

希望条件から候補時間を提案する

成功条件：

予約が保存され、再読込後も残り、

管理者画面から確認できる

今回やらないこと：

決済、複数店舗、高度なCRM

絶対条件：

予約重複を許さない

この変換工程をIntent Compilerと考える。

優秀なSkillは、ユーザーの一文を直接コードへ変えない。

一度、brief.mdやacceptance-criteria.mdへ変換する。

この中間成果物があるだけで、途中でモデルの解釈が変わりにくくなる。

3．Context Loader――必要な知識だけ読む

Skill本文へ、あらゆる情報を詰め込んではいけない。

Agent Skillsの標準仕様では、メインのSKILL.mdは500行未満、約5,000トークン未満が推奨され、詳細資料はreferences/へ分離する設計が勧められている。

悪い書き方はこれだ。

必要に応じてreferencesを読んでください。

何を、いつ読むのか分からない。

改善例はこうなる。

日本語コピーを作成または修正する場合のみ、

references/japanese-voice.mdを読む。

文末、リズム、感情表現、禁止表現の判断に使用する。

認証または権限処理を変更する場合のみ、

references/security.mdを読む。

認証境界、権限確認、秘密情報の扱いを判断する。

複数シーンの動画を制作する場合のみ、

references/transitions.mdを読む。

シーン遷移の方式とタイミングを判断する。

条件を明記すると、モデルは必要な文脈だけを読む。

Codexでは、多数のSkillを導入すると初期Skill一覧が文脈を圧迫するため、descriptionが短縮されたり、一部Skillが初期一覧から省略されたりする可能性がある。したがって、重要な用途はdescriptionの先頭へ置くべきだ。

4．Rule Compiler――お願いを検査へ変える

次のルールは弱い。

ダミー実装は禁止です。

モデルは、見た目だけのボタンを「完成」と判断するかもしれない。

強いSkillでは、次のように変換する。

HARD GATE: DISPLAY_ONLY_FEATURES

以下のいずれかに該当した場合は不合格。

• クリックしても状態が変化しない主要ボタン
• API呼び出しがハードコードされた成功値を返す
• 保存後にデータベースまたは永続ストレージへ反映されない
• TODO、FIXME、mock、placeholderが主要機能に残る
• UIは存在するが利用フローを完了できない

検証：

1. 自動スクリプトでTODO、FIXME、mock、placeholderを検索
2. 実ブラウザで主要ボタンを操作
3. APIレスポンスを確認
4. 保存後に再読込
5. 永続状態を確認

ルールは三段階に分ける。

HARD GATES

破ったら不合格。

例：

• ビルドに失敗している
• 主要機能が動かない
• 事実と異なる内容がある
• 個人情報を露出している
• コントラスト基準を満たさない
• 未承認で公開している

DEFAULTS

通常は守る。

例：

• 既存技術スタックを維持する
• 新規依存を増やさない
• モバイルファースト
• 一機能ずつ完成させる

PREFERENCES

余力があれば改善する。

例：

• 独自のアニメーション
• より印象的なコピー
• 高度なマイクロインタラクション

すべてを「絶対」にすると、本当に重要なルールが埋もれる。

5．Maker――作る役

Makerは成果物を作る。

ただし、大規模なアプリを最初から最後まで一括で作らせない。

まず、意味のある単位に分解する。

機能1：会員登録

機能2：ログイン

機能3：予約作成

機能4：予約一覧

機能5：管理者画面

一機能ごとに、完成条件を契約する。

予約作成機能の完成条件：

• 日付と時間を選択できる
• 過去日時は選べない
• 既存予約と重複できない
• 保存後に確認画面が表示される
• 再読込しても予約が残る
• APIとDBの両方で状態を確認できる

Anthropicの長時間アプリ開発実験では、Planner、Generator、Evaluatorを分け、実装前に「何を作るか」「何をテストするか」を契約する構造が使われた。EvaluatorはPlaywrightで実際のUIを操作し、APIやデータベース状態まで確認した。見た目が立派でも中身が動かない実装を、ソース確認だけで合格させないためである。

6．Checker――別の視点で採点する

生成したモデルに、そのまま自己採点させるだけでは弱い。

作った直後のモデルは、自分の意図を知っている。

「本当は動くはず」

「大きな問題ではない」

「ユーザーは気にしないだろう」

と甘く判断しやすい。

Checkerは、可能ならクリーンな文脈で起動する。

評価結果は、感想ではなく証拠を含める。

{

"criterion_id": "BOOKING-004",

"expected": "予約保存後、再読込しても予約が表示される",

"observed": "保存直後は表示されたが、再読込すると消えた",

"passed": false,

"evidence": "Reload後、GET /api/bookings returned []",

"severity": "high",

"likely_cause": "データがフロントエンドのstateにしか保存されていない",

"minimal_fix": "POST処理をDB保存へ接続し、GETで再取得する",

"retest_method": "予約作成後にページを再読込し、UI・API・DBを確認"

}

機械判定できるものはスクリプトへ任せる。

主観的なものだけLLMへ任せる。

Agent Skills公式の評価ガイドでも、JSON妥当性、ファイル数、行数、画像寸法などは検証スクリプトを使い、文章やデザインの「感じ」は人間レビューやブラインド比較を使う構成が推奨されている。

7．Repair Loop――失敗箇所だけ直す

評価が低かったからといって、すべてを作り直してはいけない。

たとえば、Webサイトの評価が次だったとする。

デザイン品質：88

独自性：74

精度：91

機能性：95

必要なのは、全ページの再実装ではない。

独自性が低い原因を探す。

• ヒーローが中央寄せの定型構造
• 紫グラデーションと白カード
• 既定アイコンを未加工で使用
• ブランド固有の写真方針がない

その部分だけを修正する。

同じ問題を2回繰り返したら、細部修正を止めて方向転換する。

現在方向の微修正を中止。

レイアウト構造、画像方針、タイポグラフィの論理を変更する。

そして、最後の版ではなく、最も評価が高かった版を残す。

デザインは、反復回数が増えるほど必ず良くなるわけではない。後半になるほど装飾が増え、途中の版の方が優れている場合もある。

8．Durable Memory――会話の外へ状態を残す

長い作業を、モデルの記憶だけに頼らない。

state.json

feature-ledger.json

decisions.md

scorecard.json

failures.json

CHANGELOG.md

これらへ残す。

{

"current_phase": "repair",

"best_checkpoint": "iteration-2",

"best_score": 88,

"failed_criteria": [

"DESIGN-ORIGINALITY-02"

],

"attempts": {

"DESIGN-ORIGINALITY-02": 1

},

"next_action": "replace generic hero composition"

}

CodexのSubagent機能も、メイン会話に探索ログやテストログを大量に流さず、専門エージェントから要約だけを戻すことで、文脈の汚染を抑える設計を説明している。ただし、Subagentはそれぞれモデルとツールを使うため、単独実行よりトークン消費は増える。

したがって、すべてのSkillを多エージェント化する必要はない。

第5章　ループの強さは三段階で選ぶ

レベル向いている仕事構成Level 1軽微な修正、短い文章、単純変換実行＋セルフチェックLevel 2実務記事、Webページ、一機能の実装Maker＋Checker＋1〜3回修正Level 3高価値アプリ、ゲーム、映像、複雑なMCP連携Planner＋Maker＋Evaluator＋実環境検証

複雑にすれば必ず良くなるわけではない。

Anthropicの実験でも、Planner・Generator・Evaluatorの構成は高品質化に寄与した一方、単独実行より大幅に高コストだった。また、モデル自体の能力が向上すると、以前は必要だった細かなスプリント構造が不要になるケースも確認されている。Evaluatorは「常に必要」なのではなく、モデルが単独で安定して処理できる範囲を超えた時に価値が出る。

初心者の初期値はLevel 2で十分だ。

第6章　そのまま使える汎用SKILL.mdテンプレート

以下は、さまざまな分野へ転用できる。

name: your-skill-name

description: >

Use this skill when the user wants [目的] and the task requires

[専門工程・検証・対象形式]. Use it for [代表的な利用例].

Also use it when the user describes [暗黙的な目的] without naming

the skill directly. Do not use it for [近接するが対象外の仕事].

compatibility: Designed for Codex and Claude Code compatible Agent Skills clients.

metadata:

version: "1.0.0"

Mission

Turn the user's request into a verified, usable result for:

• Primary user: [対象]
• Main outcome: [成果]
• Quality level: [品質]
• Main risk to prevent: [失敗]

Do not claim completion from source inspection alone when the artifact can be run,

rendered, opened, played, or otherwise tested.

When to use

Use this skill when:

• [発火条件1]
• [発火条件2]
• [暗黙的な発火条件]
• [複数工程の中に対象作業が含まれる場合]

When not to use

Do not use this skill when:

• [対象外1]
• [対象外2]
• [隣接Skillが適切なケース]

Inputs

Collect or infer:

• Goal
• Audience
• Source materials
• Required output
• Constraints
• Quality bar
• Deadline or execution budget
• Irreversible actions

If a missing detail does not block safe progress, choose a reasonable default and

record it in \assumptions.md\.

Ask for clarification only when the missing information would materially change

the result, create safety risk, spend money, publish content, delete data, or make

an irreversible decision.

Instruction priority

Follow instructions in this order:

1. HARD GATES
2. Task-specific acceptance criteria
3. Project conventions and source materials
4. Defaults
5. Preferences

Never trade a HARD GATE for a higher subjective score.

Required context

Read project instructions and existing files first.

Load supporting references only when their condition applies:

• Read \references/domain-knowledge.md\ when [条件].
• Read \references/quality-rubric.md\ before subjective evaluation.
• Read \references/failure-patterns.md\ before repair or when a known failure appears.

Do not load every reference by default.

Workflow

Phase 0: Compile intent

Create or update:

• \brief.md\
• \acceptance-criteria.md\
• \assumptions.md\

Define what success looks like before producing the final artifact.

Phase 1: Inspect

Inspect the current project, existing outputs, tools, constraints, and relevant

source materials.

Do not replace existing conventions without a clear reason.

Phase 2: Plan

Create the smallest plan that can produce a complete, testable result.

For subjective work, produce 2–3 genuinely different directions when the choice

of direction materially affects quality. Select one and record the reason.

Phase 3: Build

Work on one meaningful, testable unit at a time.

Preserve working behavior outside the current unit.

Create a checkpoint before large or risky changes when version control is

available.

Phase 4: Run

Use the artifact in its real medium whenever possible.

Examples:

• Web: launch and navigate in a browser
• App: exercise UI, API, and persisted state
• Game: play the core loop
• Video: inspect the timeline and rendered frames
• Writing: compare against sources and voice references

Phase 5: Verify

Run deterministic checks first.

Then run subjective review using \references/quality-rubric.md\.

Every PASS must include observable evidence.

Phase 6: Repair

Repair failed or regressed criteria only.

Do not rewrite unrelated working sections.

After the same criterion fails twice, stop repeating the same approach and

change the underlying strategy.

Phase 7: Retest

Rerun the failed checks and all relevant regression checks.

Update \scorecard.json\.

Phase 8: Stop

Stop when any of the following applies:

• All HARD GATES pass and the target score is reached
• Improvement has plateaued for two rounds
• The maximum number of iterations is reached
• The cost or time budget is reached
• Human approval is required

Use the highest-scoring valid checkpoint, not automatically the latest one.

Hard gates

The result fails if any of the following is true:

• [絶対条件1]
• [絶対条件2]
• [絶対条件3]
• Completion is claimed without required verification
• A failed verification is hidden or described as passing
• An irreversible operation is executed without authorization

Quality rubric

Score each category from 0 to 100:

• Correctness: [定義]
• Completeness: [定義]
• Usability: [定義]
• Originality or voice: [定義]
• Craft: [定義]

Minimum overall score: 85

A HARD GATE failure cannot be offset by a high average score.

Evaluation result format

Return:

\\`json

{

"overall_score": 0,

"hard_gates_passed": false,

"criteria": [

{

"criterion_id": "",

"score": 0,

"passed": false,

"expected": "",

"observed": "",

"evidence": "",

"severity": "",

"likely_cause": "",

"minimal_fix": "",

"retest_method": ""

}

],

"best_checkpoint": "",

"next_action": ""

}

Supporting scripts

Use scripts when available:

• scripts/validate.* — deterministic validation
• scripts/inspect.* — artifact inspection
• scripts/score.* — score aggregation

Run scripts with non-interactive arguments.

Treat non-zero exit codes as failures unless the script documentation explicitly

defines another meaning.

Completion report

Report:

1. What was created or changed
2. Where the output is
3. Assumptions made
4. Validation commands run
5. Results and evidence
6. Remaining limitations
7. Best checkpoint selected

これは標準仕様を壊しにくい共通形である。

Claude Code固有の\context: fork\、\allowed-tools\、動的コンテキスト注入などは、Claude専用Skillで必要になった時だけ追加する。Codexでは\agents/openai.yaml\を使って、UI情報、暗黙発火方針、依存ツールなどを設定できる。共通Skillの最初の一つでは、プラットフォーム固有機能を詰め込みすぎない方が扱いやすい。:contentReference[oaicite:13]{index=13}

第7章　成功した会話からSkillを作るプロンプト

実は、ゼロからSkillを考えるより強い方法がある。

まずClaudeやCodexと一度、実際の仕事を成功させる。

その会話には、次が含まれている。

• 最初の曖昧な依頼
• 途中で追加した条件
• AIが間違えた箇所
• 人間が修正した内容
• 最終的にうまくいった手順
• 本人の好み
• 現場固有の注意点

この会話をSkillへ変換する。

\\`text

この会話で行った作業を分析し、

再利用可能なAgent Skillへ変換してください。

単に会話を要約するのではなく、

次のものを抽出してください。

1. 最初の依頼には含まれていなかったが、 成功に必要だった追加情報

1. 私が途中で修正した内容

1. AIが合理的に推測すると間違える、 この分野またはプロジェクト固有のGotcha

1. 毎回再利用できる工程

1. 自動化できる検証

1. 参考資料へ分離すべき知識

1. 良い出力例と悪い出力例

1. Skillが発火すべき依頼と、 発火してはいけない近接依頼

1. 成功条件、HARD GATES、終了条件

1. 今回の一例だけに過剰適合しないために、 一般化すべき原則

一般的すぎる助言は除外してください。

例：

「高品質にする」

「適切にエラー処理する」

「ベストプラクティスに従う」

だけでは不十分です。

現実の作業で得られた、

具体的な手順、判断基準、失敗条件、検証方法を優先してください。

現在の会話だけでは足りない部分は、

推測と事実を分けてassumptions.mdへ記録してください。

完成後は、SkillありとSkillなしで評価できる

trigger evalsとoutput evalsも作ってください。

Agent Skills公式ガイドでも、一般知識だけからSkillを書かせるのではなく、実作業、API仕様、レビューコメント、過去の修正、失敗例などから専門性を抽出することが重視されている。

第8章　用途別・Skill作成プロンプトへの追加指示

以下は、最初に示した完全プロンプトの末尾へ追加する。

A．人間味のある日本語ライティングSkill

追加条件：日本語ライティング

このSkillでは、「人間らしさ」を誤字やランダムな表現として扱わないでください。

人間らしさを次の要素として設計してください。

• 観察の具体性
• 文の長短の変化
• 文末の分布
• 漢字とひらがなのバランス
• 感情に応じたリズム
• 言い切りと留保
• 読者との距離
• 説明しすぎない余白
• 強調する一文の短さ
• 個人固有の語彙

文章制作を次の工程へ分けてください。

1. 事実と主張の整理
2. 読者の感情曲線
3. 構成
4. 声への変換
5. AI的な均一さの除去
6. 事実保全
7. 音読を想定したリズム確認

以下を検査する仕組みも入れてください。

• 同じ文末の連続
• 同じ長さの文の連続
• 接続語の過剰使用
• 抽象語の多さ
• 根拠のない感情
• 捏造された体験
• 不自然な箇条書き
• すべてを説明し切る文章
• 見出しの過剰使用
• 定型的なAI表現

本人の文章サンプルがある場合は、

voice-profile.mdを作ってください。

ただし、本人の言葉をそのまま大量に複製せず、

特徴を抽象化してください。

最終評価では、

事実性、声、リズム、具体性、感情の移動、読者との距離を

別々に採点してください。

B．非エンジニア向けバイブコーディングSkill

追加条件：非エンジニア向けバイブコーディング

ユーザーの曖昧な依頼から、すぐコードを書き始めないでください。

最初に次を作ってください。

• product-brief.md
• user-journeys.md
• acceptance-criteria.md
• out-of-scope.md
• feature-ledger.json

専門用語ではなく、

ユーザーが実際に何を達成できるかで仕様を書いてください。

例：

悪い仕様：

「CRUD APIを実装する」

良い仕様：

「管理者が商品を追加し、

ページを再読込しても商品が残り、

一般ユーザーの商品一覧へ表示される」

一機能ずつ完成させてください。

各機能について、

UI、API、保存状態、エラー状態を確認してください。

以下をHARD GATEにしてください。

• 主要ボタンが見た目だけ
• データがstateにしか保存されていない
• APIが固定値を返す
• 認証や権限が画面表示だけ
• エラー状態が未実装
• テストせず完成と言う
• TODO、FIXME、mock、placeholderが主要機能に残る

最終報告は、非エンジニアにも分かる言葉で、

「何ができるようになったか」

「どう試すか」

「何がまだできないか」

を説明してください。

C．1000万円級を目指すWeb制作Skill

「1000万円で発注した品質」をSkillだけで保証することはできない。

高額なWeb制作には、事業理解、顧客調査、ブランド戦略、撮影、コピー、デザイン、実装、検証、プロジェクト管理まで含まれる。

しかし、その制作工程へ近づけることはできる。

追加条件：プレミアムWebデザイン

HTMLやコンポーネントを書く前に、

必ずVisual Identity Gateを通してください。

次をDESIGN.mdへ定義してください。

• ブランドの目的
• 対象顧客
• 感情
• ブランドの約束
• 競合との差
• 色の役割
• タイポグラフィ
• 写真またはイラスト方針
• 余白
• レイアウト原則
• モーション原則
• 使用しない表現

根拠なく、次へ自動的に逃げないでください。

• 紫グラデーション
• 白いカードの羅列
• 中央寄せヒーロー
• 汎用SaaSレイアウト
• 未加工のUIライブラリ既定値
• 意味のない光彩
• 過剰な角丸
• ストック写真の無目的使用

実装前に、2〜3個の異なるArt Directionを作ってください。

単なる色違いではなく、

構図、密度、タイポグラフィ、画像、動きの論理を変えてください。

評価軸：

• Design Quality：全体が一つの世界として成立しているか
• Originality：独自の判断があるか
• Craft：文字組み、余白、色、精度
• Functionality：迷わず目的を達成できるか

Design QualityとOriginalityを重く評価してください。

ブラウザで次を確認してください。

• 375px
• 768px
• 1440px
• 長い文章
• 短い文章
• 空状態
• エラー状態
• キーボード操作
• フォーカス表示
• メニュー
• フォーム
• 主要CTA
• リンク切れ
• コントラスト
• 横スクロール
• オーバーフロー

静止画だけで合格させず、

実際にページを操作してください。

Anthropicのフロントエンド実験でも、デザイン品質、独自性、精度、機能性を分け、EvaluatorがPlaywrightで実ページを操作しながら評価するループが使われた。特に、モデルが得意な基本的精度だけでなく、デザイン品質と独自性を重く評価することで、汎用的なAIデザインから離れる試みが行われている。

D．アプリ制作Skill

追加条件：アプリ制作

画面数ではなく、ユーザーの状態遷移を中心に設計してください。

次を定義してください。

• ユーザー種別
• 権限
• 入力
• 保存状態
• 非同期処理
• 失敗
• 再試行
• 空状態
• ローディング
• 監査
• 通知
• セッション

各主要機能を、次の四面から検証してください。

1. UI
2. API
3. Databaseまたは永続状態
4. ログまたはエラー

「画面が表示された」を完成条件にしないでください。

例：

設定変更機能の完成条件：

• 権限を持つユーザーが変更できる
• 権限がないユーザーは変更できない
• 保存後に再読込しても値が残る
• APIレスポンスが正しい
• DB値が更新される
• 失敗時に復旧方法が表示される

AI機能を追加する場合は、

見た目だけのチャット欄を作らず、

アプリ自身の機能をツール経由で操作できるか検討してください。

E．ゲーム制作Skill

追加条件：ゲーム制作

コンテンツ量より先に、

最小の「遊べる縦切り」を完成させてください。

最初に次を定義してください。

• ゲームの柱
• 30秒のコアループ
• プレイヤーの目的
• 失敗
• 報酬
• 学習
• 緊張と解放
• リトライ
• 1プレイの長さ

評価を三つへ分けてください。

Technical Checker：

• クラッシュ
• FPS
• 入力
• 当たり判定
• セーブ
• 再現性

System Checker：

• 難易度
• 経済
• 攻略の単調化
• 詰み
• 報酬バランス

Feel Checker：

• 入力遅延
• ヒット感
• 音
• カメラ
• 予兆
• リトライ速度
• もう一度遊びたくなるか

固定seedや決まった入力列を使い、

変更前後を比較できるテストも作ってください。

スクリーンショットが美しいだけで合格させず、

実際にコアループをプレイしてください。

F．HyperFrames動画編集Skill

追加条件：HyperFrames動画制作

HTMLを書く前に、必ずDESIGN.mdまたはvisual-style.mdを作成してください。

工程を次の順序にしてください。

1. What 視聴者に何を体験させるか

1. Structure シーン、構成、トラック、素材

1. Timing 尺、テンポ、転換点、感情の山

1. Layout 各シーンのHero Frameを静的に完成させる

1. Animate 完成位置を基準に入口と動きを追加する

静的レイアウトが完成する前に、

アニメーションで位置をごまかさないでください。

次をHARD GATEにしてください。

• 視覚アイデンティティなしでHTMLを書かない
• Math.randomや時刻依存を使わない
• 無限repeatを使わない
• タイムライン登録を忘れない
• 同一要素の同一プロパティを競合させない
• 複数シーンで遷移なしのジャンプカットを使わない
• テキストオーバーフローを放置しない
• コントラスト警告を放置しない
• 最終レンダーを確認せず完成と言わない

制作後に次を実行してください。

• npx hyperframes lint
• npx hyperframes validate
• npx hyperframes inspect
• animation map
• draft render
• final render

評価役を三つへ分けてください。

Story Checker：

物語、情報密度、冒頭の約束、感情の山、余韻

Visual Checker：

タイポグラフィ、構図、視線、色、動きの階層

Technical Checker：

タイムライン、メディア、オーバーフロー、コントラスト、

決定性、レンダー

失敗したシーンだけを修正してください。

HyperFramesの中核Skillでも、制作工程はWhat、Structure、Timing、Layout、Animateの順で整理され、視覚アイデンティティを先に定め、最も要素が見えるHero Frameを静的に作ってからアニメーションを加える設計になっている。

また、決定性、有限リピート、タイムライン登録、シーン遷移、オーバーフロー、コントラスト、アニメーションマップなどが検証項目として定義されている。

G．動画生成MCP・シナリオ制作Skill

追加条件：動画生成MCPとシナリオ制作

ユーザーの一文を直接、動画生成モデルへ送らないでください。

次の変換を行ってください。

目的

→ 視聴者への約束

→ 感情の変化

→ Beat Sheet

→ Scene Objective

→ Shot Spec

→ Provider Adapter

→ MCP Tool Call

動画モデル固有の仕様と、

物語やショット設計を分離してください。

共通のShot Specには次を含めてください。

• shot_id
• story_purpose
• duration
• subject
• action
• environment
• camera
• composition
• lighting
• palette
• motion
• continuity_in
• continuity_out
• negative_constraints
• acceptance_criteria
• reference_assets
• seedまたは再現用ID

各動画プロバイダーには、

共通Shot Specを変換するAdapterを作ってください。

モデル名、尺、解像度、参照画像、API仕様など、

変化しやすい情報はreferencesまたはMCP Resourcesへ分離してください。

まず安価なキーフレーム、低解像度、短尺で構図を確認してください。

Continuity Checkerは次を確認してください。

• 顔
• 衣装
• 小道具
• 画面方向
• 光
• 時間帯
• カメラ速度
• キャラクターの目的
• ショットの物語上の役割

失敗したショットだけを再生成してください。

映像全体を毎回作り直さないでください。

プロンプトへcinematic、masterpiece、8Kなどの形容詞を足すだけで

品質を上げたことにしないでください。

被写体の動詞、カメラ、構図、光、連続性、禁止条件を

構造化してください。

第9章　既存Skillを改善するプロンプト

Skillは一度作って終わりではない。

以下を使って、実行結果から改善する。

以下のAgent Skillを、実際の評価結果にもとづいて改善してください。

入力：

• 現在のSKILL.md
• references
• scripts
• trigger eval結果
• output eval結果
• 実行ログ
• failed assertions
• 人間レビュー
• トークンと実行時間
• 旧版との比較結果

改善工程：

1. 失敗を次へ分類する

• Trigger
• Context
• Procedure
• Tool
• Verification
• Evaluator
• Stop condition
• Memory

1. 症状ではなく根本原因を特定する

1. 次のどれが必要か判断する

• descriptionを直す
• 手順を明確にする
• 参考資料を追加する
• 参考資料を削る
• Script化する
• テストを直す
• Evaluatorを厳しくする
• 終了条件を直す
• Skillを二つに分割する
• 指示を削る

1. 失敗したテストの具体的な単語だけをdescriptionへ足すなど、 過剰適合をしない

1. 指示の追加だけでなく削除も検討する

1. 旧版を保存する

1. 新版を別のクリーンな文脈で評価する

1. 学習に使っていないHeld-outテストでも確認する

1. 最後の版ではなく、 検証セットで最も高得点だった版を採用する

出力：

• failure-analysis.md
• proposed-changes.md
• 更新後のSkill
• changelog.md
• regression-evals.json
• 旧版と新版の比較

公式の評価ガイドでも、各テストをSkillあり・なし、または旧版・新版で実行し、クリーンな文脈を使い、具体的なAssertion、証拠、トークン、実行時間を比較する方法が推奨されている。

第10章　発火しないSkillを直すプロンプト

Skillの中身は優秀なのに、呼ばれない。

この問題は非常に多い。

このSkillのdescriptionを、発火精度の観点から改善してください。

次を作成してください。

1. 発火すべき依頼10件
2. 発火してはいけない近接依頼10件
3. それぞれの分類理由
4. 現descriptionの不足
5. 現descriptionが広すぎる箇所
6. 改善description案を3個
7. 各案の想定メリットと誤発火リスク

テストでは次を混ぜてください。

• Skill名を明示する依頼
• Skill名を言わない依頼
• 口語
• 誤字
• 一文だけの依頼
• 長い背景説明
• 複数工程に埋もれた依頼
• 同じキーワードを使う別作業

可能なら各依頼を3回ずつ実行し、

trigger rateを記録してください。

テストをtrain 60%、validation 40%へ分けてください。

descriptionの改善にはtrain結果だけを使用し、

最終案はvalidation結果で選んでください。

最後の案を自動採用せず、

validationで最も高得点だった案を採用してください。

Agent Skillsの公式ガイドでも、同一依頼を複数回試し、発火率を測り、TrainとValidationを分け、最後の案ではなくValidation成績のよい説明を選ぶ方法が紹介されている。

第11章　検証スクリプトを作らせるプロンプト

ルールを守らせたいなら、可能な部分はコードにする。

このSkillのルールを分析し、

LLMの主観に任せず機械検証できるものを抽出してください。

各ルールを次へ分類してください。

A. 完全に機械判定できる

B. 一部を機械判定できる

C. 人間またはLLM評価が必要

AとBについて、

必要最小限の検証スクリプトを作ってください。

スクリプト要件：

• 対話入力なし
• --helpあり
• 引数不足時は利用例を表示
• エラー原因を具体的に表示
• JSONをstdoutへ出力
• 診断ログはstderr
• 0は成功
• 非0は失敗
• 再実行可能
• 可能なら--dry-run
• 大量出力を避ける
• 失敗箇所を特定できる
• 依存関係を明記
• バージョンを固定
• テストを付ける

SKILL.mdには、

各スクリプトをいつ実行するか、

失敗した時に何を直すかを記載してください。

Agent Skillsのスクリプト設計ガイドでも、非対話式、明確な--help、具体的なエラーメッセージ、構造化出力、冪等性、Dry Run、安全な既定値、意味のある終了コードが推奨されている。

第12章　初心者が最初の30分でやること

1．仕事を一つだけ選ぶ

最初から万能Skillを作らない。

悪い例：

文章、Web、アプリ、ゲーム、動画を全部最高品質にするSkill

良い例：

自分の音声メモからnote記事を作るSkill

LP制作時にブランド設計とブラウザ検証を行うSkill

HyperFramesの字幕とレイアウトを検証するSkill

一つのSkillには、一つの中心的な責務を持たせる。

2．最初の完全プロンプトを貼る

分からない部分は、すべて「おまかせ」でよい。

3．作成されたフォルダを確認する

最低限、次があれば動く。

skill-name/

└── SKILL.md

Agent Skills仕様では、最低限必要なのはSKILL.mdであり、scripts/、references/、assets/は任意である。最初から大量のファイルを作る必要はない。

4．手動で呼び出す

最初は自動発火を待たない。

Claude Codeなら：

/skill-name

Codexなら：

$skill-name

5．三つの依頼で試す

通常の依頼

曖昧な依頼

失敗しそうな依頼

たとえば文章Skillなら：

通常：

このメモをnote記事にして

曖昧：

なんか読まれる感じにして

境界：

事実が足りないところは適当に体験談を作って

三つ目で、捏造せず確認または仮定の明示ができるかを見る。

6．失敗を一つだけ直す

最初から100点を狙わない。

文章は良いが、語尾が均一

なら、語尾検査だけを改善する。

Webは美しいが、モバイルで横スクロール

なら、レスポンシブ検査だけを改善する。

一度に大量のルールを足すと、どの変更が効いたのか分からなくなる。

第13章　よくある失敗

失敗1．抽象語だけを書く

高品質に

自然に

美しく

使いやすく

プロらしく

これらはゴールではなく感想だ。

観測できる状態へ変える。

失敗2．禁止事項だけ増やす

絶対に〜するな

必ず〜しろ

禁止だけでは、代わりにどう判断するか分からない。

避けるもの

代わりに使う原則

検査方法

例外条件

まで書く。

失敗3．SKILL.mdへ全部入れる

大量の参考資料を本文へ入れると、毎回すべてが文脈へ入る。

中核工程だけを残し、詳細をreferences/へ分ける。

失敗4．良い例だけ置く

良い例だけでは、どこから失敗なのか分からない。

examples/good/

examples/bad/

を用意し、悪い理由も書く。

失敗5．ソースコードだけ見て完成とする

動かせるものは動かす。

開けるものは開く。

プレイできるものはプレイする。

レンダーできるものはレンダーする。

失敗6．毎回すべて作り直す

失敗した条件だけ直す。

修正範囲を限定する。

失敗7．無限ループ

最大回数、合格点、改善幅、費用上限を決める。

ループは、長く回すほど偉いわけではない。

失敗8．万能Skillを作る

万能Skillは、発火条件も評価方法も曖昧になる。

文章、Web、アプリ、ゲーム、動画は、共通のLoop Coreを持たせつつ、領域別Skillへ分ける。

第14章　公開前チェックリスト

Skill本体

• nameは小文字、数字、ハイフンのみか
• フォルダ名とnameが一致しているか
• descriptionに何をするかと、いつ使うかがあるか
• 発火してはいけない境界が明確か
• メインSkillが巨大化していないか
• 詳細資料を必要時だけ読むようになっているか
• 一般論ではなく、固有の判断やGotchaがあるか

工程

• 作る前に成功条件を定義しているか
• HARD GATES、DEFAULTS、PREFERENCESを分けているか
• 作成後に実物を確認しているか
• 生成役と評価役を必要に応じて分けているか
• 失敗条件に証拠があるか
• 失敗箇所だけを修正しているか
• 終了条件があるか
• 最良版を保存しているか

評価

• 通常ケースがあるか
• 曖昧ケースがあるか
• 境界ケースがあるか
• 発火すべき例があるか
• 発火してはいけない近接例があるか
• Skillなし、または旧版と比較したか
• 機械判定できるものをスクリプト化したか
• 主観品質をブラインド比較したか
• 人間レビューを残したか
• トークンと時間の増加に見合うか

結論　Skill作成で最初に指示すべきこと

初心者が、最初から完璧なSKILL.mdを書く必要はない。

AIへ伝えるのは、次だけでいい。

私は何を繰り返しているのか。

何ができれば成功なのか。

どんな失敗を避けたいのか。

理想に近いものは何か。

その情報を、Skill作成プロンプトによって次へ変換させる。

曖昧な依頼

↓

目的

↓

発火条件

↓

成功契約

↓

工程

↓

HARD GATES

↓

検証

↓

評価

↓

修正

↓

再検証

↓

終了

↓

学習

強いSkillは、モデルへ「もっと頑張れ」と命令しない。

• 雑に始められない
• 検証せず終われない
• 失敗を隠せない
• 同じ修正を延々と繰り返せない
• 次回、同じ失敗を忘れない

そんな環境を作る。

Skillとは、賢いプロンプトではない。

AIが高品質な仕事を再現するための、小さな業務システムである。