Amazon Quick で SKILL を作成する完全ガイド

本記事では、実際の事例である「SEO 健康診断」スキルが誕生するまでの全過程を基に、SKILL の作成に必要な作業、使用するコマンド、そして遭遇した落とし穴をまとめます。自分の繰り返し作業を再利用可能なスキルとして固定化したい人に適しています。

1. SKILL とは何か、なぜ作成するのか

SKILL とは、一連の多段階ワークフローを固定化した再利用可能な能力パッケージです。一度作れば、以後は一言でフロー全体を起動でき、毎回説明し直す必要がありません。

SKILL は本質的に一つのフォルダです：

skill-name/
├── SKILL.md          ← 核心：流程说明 + 触发词 + 输入 + 经验
├── scripts/          ← 可选：可复用的代码脚本
│   └── *.py
└── evals/            ← 可选：测试用例
    └── evals.json

SKILL 化に適しているサイン：繰り返し行う作業である、ステップが 2 以上ある、明確な成果物がある、対象（URL/顧客/プロジェクト）を変えても使える。

2. SKILL 作成の全体フロー（5 ステップ）

スキルの作成自体にも「メタスキル」が誘導します。核心はこの 5 ステップです：

3. 段階的に分解：各ステップで具体的に何をするか

ステップ 1：まずワークフローを通しで動かす（最重要）

スキル構築を急がないこと。まず実際のニーズを一つ取り上げて最後までやり切る。例えば：「この Web ページの SEO をチェックして」。この過程で：

• 明確にする入力とは何か（1 つの URL？複数の URL？）
• 明確にする成果物とは何か（1 つのレポート？どの形式？）
• 各ステップでどの能力を使ったかを記録する（Web ページを開く、コードを実行する、Excel を生成する……）

実践からの教訓：私たちの SEO スキルは、ある企業の公式サイトの複数ページを実際に徹底的に審査し、レポート形式を何度も調整した末に、ようやくスキルとして抽出したものだ。途中でユーザーから次々と要望が出た（Bing 基準の追加、公式ソースの確認、実行マトリクスへの変更、2 段階への分割……）が、これらはすべてスキルの中で最も価値ある部分になった。

ステップ 2：スキルの骨組みを確認

AI に明確に伝える（または提案させる）：

ステップ3：会話データを抽出

このステップはツールが自動で完了する：先ほど実行した会話をスキャンし、使用したツール一覧を抽出して、YAML frontmatter付きのSKILL.md骨格を生成する。あなたはステップ2で決めた技能名、トリガーワード、入力項目、表示名、アイコンを提供するだけでよい。

指示：extract_session_data

ステップ4：SKILL.mdを書く（核心的な創作）

骨格をベースに以下の部分を補完する：

① frontmatter（ファイルヘッダー）

---
name: seo-audit-skill
display_name: 「SEO 体检」
description: "一句话说清楚它做什么、什么时候该触发"
icon: "🔍"
trigger: SEO体检 audit 网站优化 网站SEO
inputs:
  - name: page_url
    description: "要体检的页面网址"
    required: true
scripts: [seo_audit.py, seo_matrix.py]
---

② Overview

2〜3文で何をするか、いつ使うかを明確に説明する。

③ Workflow（ステップ分割）

各ステップにモード（deterministic 固定アクション / agentic 判断が必要）、入力、出力、検証方法、失敗時の対応を明記する。「なぜ」を多く語り、硬直した「必須/禁止」は少なく書く——スキルを実行するAIは「理屈を語る」方をよく理解する。

④ Output

最終的な成果物がどのような形になるか、フォーマットを明確に定義する。

⑤ Lessons Learned（経験）

これはスキル品質の分水嶺であり、4つのブロックに分かれる：

• Do：どのような方法が有効か
• Don't：どのような落とし穴を避けるべきか
• Common Failures：よくあるエラー＋対処法
• When to Ask the User：いつ止めて人に聞くべきか

実践的な教訓：このスキルのLessonsには実際に踏んだ落とし穴が満載——中国語では \uXXXX エスケープを使わない、CSV書き込みには utf-8-sig Excel文字化け防止、画像alt欠落率が異常に高いのは大半が遅延読み込みの誤検知（「要確認」とマークし、直接欠落と判定しない）、一部ドメインは一括クロールをブロックするためブラウザで検証が必要……これらの「血と涙」がスキルを次回より安定して実行させる。

⑥ スクリプト（オプションだが強く推奨）

フロー内に繰り返し書くコードがあれば、スクリプトに抽出して scripts/，SKILL.md で参照します。私たちは「ページシグナル収集 JS」と「複数ページマトリクス生成」を 2 つのスクリプトにして、出力フォーマットが毎回一致するようにしています。

ステップ 5：保存 + テスト

• 保存コマンド：save_skill（スキル名 + 完全な SKILL.md + スクリプト）
• テスト生成：generate_skill_evals（テストケースをいくつか自動生成）
• その後実際に一度実行して検証——単一ページと複数ページの 2 つのシナリオで実測し、実際の問題を識別できることを確認しました（例えば複数の 404 リンク切れを検出し、ソーシャル共有タイトルとページタイトルの不一致を発見）。

4. 作成後のイテレーションと配布

イテレーション改善

指示：load_skill_for_improvement。スキルは一度で完成するものではありません。数回使った後に必要に応じて改善します：

• フロー変更、出力フォーマット追加、トリガーワード調整
• 保存時に同じスキル名を使用すればその場で上書きできます（旧バージョンは自動バックアップ）

実践：このスキルは何度もイテレーションを重ねました——Bing 標準の追加、実行マトリクスのフォーマット変更、2 段階への分割、Excel+Markdown のデュアル出力追加、列名とサンプルの整合修正、最後に名前変更。毎回 load_skill_for_improvement → 変更 → save_skill 上書き。

名前変更

frontmatter の name と display_nameを変更し、新しい名前で save_skill、その後古いスキルフォルダを削除。

パッケージ配布

スキルフォルダ全体を zip に圧縮すれば、バックアップ、別の PC への移行、または同僚への共有（相手の skills ディレクトリに配置）が可能です。

クロスツール移植

他の AI ツール（ChatGPT/Claude/Gemini）で使用する場合は「脱プラットフォーム化」が必要です：専用ツール名を汎用的な能力記述（「Web ページを開く」「コードを実行する」）に書き換え、スクリプトを自己完結型の Markdown に埋め込めば、そのままシステムプロンプト/カスタム指示として貼り付けられます。

5. よく使うコマンド早見表

六、落とし穴チェックリスト（実際の失敗事例より）

1. まず動かしてから固定化——ゼロからスキルを書かないこと。
2. 入力には変わる値だけを入れる——固定値はフロー内にハードコードする。
3. Lessons Learned には実際の経験を書き切る——これがスキルを「使うほど安定」させる鍵。
4. 重複コードはスクリプト化する——出力形式の一貫性を保ち、token を節約。
5. 保存後は必ずテスト——単一ページ＋複数ページで実際に一度実行し、実際の問題を識別できるか検証する。
6. エンコードの落とし穴（中国語/コード生成を伴う場合）：ファイル書き込みは encoding="utf-8"、CSV は utf-8-sig、使わないこと \uXXXX エスケープ、PDF の中国語は内蔵 CID フォントを使用。
7. イテレーションは同名で上書き——name 変更なし、旧版は自動バックアップ。

結び

SKILL 作成の本質は：一度成功したワークフローを、その中の判断と教訓ごと「次回は一言で再現できる」能力としてカプセル化すること。 優れたスキルは、手順を記録するだけでなく、「どうすればこれを正しくできるか」という経験も記録している。

まず物事を美しくこなし、それを再利用可能にする——これが SKILL 作成のすべての心構え。