みんな一度は経験しているはずです。あなたは集中モードに入っていて、AIのコーディングアシスタントとペアプログラミングしています。そして、いつもと少し違うこと——SVGの図を生成する、ナレッジベースから文脈を取得する、あるいは日常的に使う特定のデザインパターンをひな形として作らせる——を頼むんです。すると、それは……うまくいきません。
アシスタントは一般的なボイラープレートを出してきます。あるいはもっと悪いのは、見た目はそれっぽいのに、あなたのワークフローに対して微妙に間違っているものを、自信満々に生成することです。結果を直すのに、あなた自身が最初からやっていた時間よりも多くの時間を費やすことになります。
根本の問題は、AIアシスタントが「バカ」だからではありません。ドメイン固有の指示なしに動く、ゼネラリストであることが問題なのです。
なぜあなたのAIアシスタントはいつも間違えるのか
最新のAIコーディングアシスタント——Claude Code、GitHub Copilot、Cursorなど、どれであっても——は巨大なデータセットで訓練されています。何でも少しずつは分かっています。しかし「何でも少しずつ」は、デザインシステムが要求する通りの見た目でコンポーネントを作りたいときや、特定のパラメータで画像を生成したいときに必要なものではありません。
核心となるのは 文脈の欠乏（context starvation） です。あなたのアシスタントは次のことを知りません：
- チームが一般的なタスクで好むパターン
- 外部ツール（画像API、検索エンジン、デザインツール）をどう連鎖させるか
- あなたの特定のユースケースにおける「良い出力」が何か
これは、技術的に優秀な新入社員がそれでもオンボーディングを必要とするのと同じ理由です。文脈のない生の能力では、結果はおおむね中途半端になります。
解決策：再利用できる指示としてのカスタムスキル
勢いを増している解決策は、スキルという考え方です。つまり、AIアシスタントに対して特定のタスクをうまく行う方法を教える、モジュール化された再利用可能な指示セットです。
スキルをステロイド版のプロンプトテンプレートだと思ってください。毎回、あなたのアシスタントに何か特定のことをさせるために同じ指示を貼り付けるのではなく、スキルを一度定義し、名前で呼び出します。
基本的なスキル定義が概念的にどんなものかというと、例えばこうです：
# skill: web-design-helper
name: Web Design Assistant
description: Generates responsive web components following modern CSS practices
instructions: |
When asked to create a web component:
1. Use semantic HTML5 elements
2. Prefer CSS Grid and Flexbox over floats
3. Include mobile-first responsive breakpoints
4. Add ARIA attributes for accessibility
5. Use CSS custom properties for theming
重要な洞察は、スキルは魔法ではないということ——それは構造化された文脈だ、という点です。出力生成を始める前に、必要な知識をアシスタントへ先回りして与えるのです。
自分のスキルコレクションを作る
実際にどうセットアップするか、手順を追って説明します。使っているAIツールが何であってもこのパターンは機能しますが、具体的な設定形式は異なる場合があります。
ステップ1：反復して起きるイライラを特定する
まずは、今週あなたがAIアシスタントを直した回数をすべてリストアップしてください。私はそうしました。そして3つのカテゴリが見つかりました：
- 出力のフォーマット — 間違ったスタイルのコードを作り続けていた
- ツールの使い方 — 自分が日常的に使っている外部APIを呼び出す方法を知らなかった
- ドメイン知識 — プロジェクトの慣習に関する文脈が欠けていた
ステップ2：十分に具体的なスキル指示を書く
曖昧な指示は曖昧な結果を生みます。次の2つのアプローチを比べてみてください：
# Bad: Too vague
Generate good images when asked.
# Good: Specific and actionable
When generating images:
- Use the DALL-E API endpoint at /v1/images/generations
- Default to 1024x1024 unless the user specifies a size
- Always include a "revised_prompt" field in the response
- For UI mockups, use a clean, minimal style with a white background
- For diagrams, prefer dark backgrounds with high-contrast elements
- Return the image URL and the prompt used so the user can iterate
2つ目のバージョンでは曖昧さが消えます。あなたの文脈における「画像を生成する」が、アシスタントにとっては明確になります。
ステップ3：ドメインごとにスキルを整理する
コレクションが増えてくると、構造が重要になります。私がうまくいくと見てきたパターン——そしてGitHub上のオープンソースのスキルコレクションである ConardLiのgarden-skills でも使われているもの——は、スキルを「能力ドメイン」でグループ化することです：
skills/
├── web-design/ # HTML/CSS generation, responsive layouts
├── knowledge/ # RAG retrieval, documentation search
├── image-generation/ # Image API integration, prompt crafting
├── code-review/ # Style checks, security scanning
└── devops/ # CI/CD templates, Docker configs
スピードを出したいなら、このgarden-skillsリポジトリを見てみる価値があります。Webデザイン、知識の取得、画像生成など、よくあるユースケースを網羅したキュレーション済みのコレクションです。ゼロからすべて作る代わりに、フォークしてスキルをあなたのワークフローに合わせてカスタマイズできます。
ステップ4：テストして改善する
スキルはコードと同様にデバッグが必要です。私のプロセスはこうです：
# known inputでスキルをテストする
# 出力を、あなたが手作業で作るものと比較する
# 次の3点を見る：
# 1. 指示に一貫して従っているか？
# 同じプロンプトを3〜4回実行する — 出力が大きく揺れるなら、
# 指示が曖昧すぎる
# 2. エッジケースに対応できているか？
# 範囲内ではあるが珍しい入力を試す
# 3. うまく失敗できているか？
# スキルの範囲から少し外れたことをやるように頼む
# 制限を認めるべきで、幻覚（hallucinate）を起こさない
スキルが「固まった」と感じるまで、私は通常2〜3ラウンドの改良を行います。
避けるべきよくある落とし穴
スキルを広げすぎないでください。 「画像で何でもやる」というスキルは、生成・編集・分析のための3つの絞り込んだスキルよりも性能が悪くなります。スコープを狭くするほど、より具体的な指示になり、結果も良くなります。
頻繁に変わる値をハードコードしないでください。 APIエンドポイントやモデルバージョンがしょっちゅう変わるなら、スキル指示の中に値を直接埋め込むのではなく、設定ファイルを参照してください。
例を省略しないでください。 どのスキル定義にも追加できる最も効果的な要素は、具体的な入力／出力の例です。LLMはパターンから学びます——あなたが望むものを見せてください。
## 例
Input: "ユーザープロフィール用のカードコンポーネントを作成する"
Output:
- ルート要素として <article> を使用したセマンティックHTML
- 内部レイアウトにCSS Grid
- アバター、名前、プロフィール本文、アクションボタンのためのスロット
- 控えめな持ち上がり（elevation）の変化を伴うホバー状態
防止: スキル優先のワークフローを構築する
本当の勝ちどころは、個々のインタラクションを直すことではありません。考え方を切り替えることです。新しいプロジェクトを始めるときや新しいツールを導入するときは、次に尋ねてください:「ここでAIアシスタントを役立つ存在にするには、どんなスキルが必要か？」
READMEやリンタ設定と並行して、スキルを最初から書き出してください。スキルは、プロジェクトの開発者体験（developer experience）インフラの一部として扱います。
役立つ習慣をいくつか:
- スキルをバージョン管理する — スキルはプロジェクトとともに進化します
- スキルをチームで共有する — 複数の人がAIアシスタントを使う場合、一貫性が重要です
- スキルを四半期ごとに見直す — 使っていないものは削り、変化してズレたものは更新します
- 還元する — 役に立つものを作ったらオープンソース化して、他の人が恩恵を受けられるようにしましょう
平凡なAIコーディング体験と素晴らしい体験の差は、通常モデルではなく、あなたが与えるコンテキストです。スキルは、イライラした修正を1回ずつ積み重ねるのではなく、そのギャップを体系的に埋めるための方法です。
