ある朝、いつも使っている自作スキルが呼ばれませんでした。プロンプトはいつもと同じ。違うのは、前日に入った組み込みの Guide スキルだけです。エージェントは Guide スキルの説明に引っ張られ、私が用意した手順ではなく、汎用的な案内を返してきました。
個人開発で複数のアプリとサイトを並行して回していると、スキルは「自分の手順を固定する」ための土台になります。その土台が、組み込みスキルの追加で静かにずれる。これは放っておくと、毎回プロンプトを言い換えて回避するという、いちばん消耗するやり方に落ちていきます。
ここでは、発火を推測でなく観測に置き換え、説明文と命名で交通整理する方法を整理します。
スキルは「説明文のキーワード」で選ばれている
Antigravity のスキルは、SKILL.md の冒頭に置く説明文（description）を手がかりに選ばれます。ユーザーの依頼文と、各スキルの説明文を突き合わせ、いちばん合致したものが発火する。つまり発火の主導権は、スキル名ではなく説明文が握っています。
組み込みの Guide スキルは、その説明文が広めに書かれています。「使い方を案内する」「進め方を示す」といった一般語が並ぶため、自作スキルの説明文と語彙が重なりやすい。重なった瞬間、どちらが選ばれるかは安定しなくなります。
最初にやるべきは、衝突しているかどうかを思い込みで決めないことです。
まず「なぜ選ばれたか」を観測する
対処の前に、いま何が起きているかを確定させます。手順はこうです。
- 同じ依頼文を、明示呼び出し（
/ でスキル名を直接指定）で一度実行し、自作スキルが正しく動くこと自体は確認する。
- 次に、明示せず自然文だけで依頼し、どのスキルが発火したかをエージェントの応答冒頭で確認する。
- 発火したスキルが意図と違う場合、自作スキルと組み込みの説明文を並べ、どの語が重なっているかを目で照合する。
- 重なっている語を、依頼文・説明文のどちらに含めると発火が変わるかを、一語ずつ変えて再現する。
ここで大切なのは、推測で説明文を書き換えないことです。一語ずつ動かして、発火の境目を実際に見てから直す。境目を見ずに直すと、別の依頼文で逆の衝突が起きて、いたちごっこになります。
私自身の例でも、発火が毎回ぶれていた依頼文が、説明文に固有トリガー語を1行足しただけで、3回連続で同じ自作スキルに収束しました。逆に、境目を見ずに語を2つ同時に動かしたときは、別の依頼文で組み込みが再び前に出てしまい、直すのに2往復よけいにかかりました。観測してから一語ずつ、が結局いちばん速い直し方です。
| 観測された症状 | ありがちな原因 | 最初に試すこと |
|---|
| 自作スキルが呼ばれない | 組み込みの説明文が依頼文により近い | 説明文に固有トリガー語を足す |
| 二つ呼ばれて応答が混ざる | 説明文の語彙がほぼ同一 | 片方の守備範囲を説明文で狭める |
| 毎回違うスキルが出る | どちらにも弱く合致している | 明示呼び出しを既定運用にする |
| 意図せず Guide が出る | 依頼文が「進め方」を尋ねる形 | 依頼文を動詞+対象の命令形にする |
説明文は「固有トリガー語」で書く
衝突を減らすいちばん効く一手は、自作スキルの説明文を、組み込みと重ならない固有の語で書くことです。一般動詞（案内する・説明する・進める）は組み込みと必ず競合します。代わりに、自分のワークフロー固有の名詞と、具体的な対象を入れます。
衝突しやすい説明文の例です。
---
name: release-checklist
description: リリースの進め方を案内します。手順を順番に示します。
---
これは Guide スキルの「進め方を案内」とほぼ同じ語彙で、競合します。固有語に寄せると、こう変わります。
---
name: release-checklist
description: |
iOS/Android アプリのストア申請前チェックを実行します。
バージョン番号・スクリーンショット差分・dSYM 添付・
リリースノート日英の整合をこの順で検証するときに使います。
トリガー: ストア申請前チェック, リリース前検証, 申請チェックリスト
---
ポイントは三つあります。第一に、固有名詞（ストア申請・dSYM・日英整合）で守備範囲を狭めること。第二に、いつ使うかを「〜するときに使います」と条件で書くこと。第三に、明示的なトリガー語を一行足しておくこと。説明文が狭く具体的なほど、組み込みの広い説明文に勝ちやすくなります。
命名は「動詞+対象」で具体化する
スキル名そのものも発火の手がかりになります。helper や assistant のような一般名は、どの依頼にも弱く合致してしまい、選ばれる理由にも外される理由にもなりません。release-checklist や admob-fill-rate-diagnosis のように、動詞または対象が一目で分かる名前にします。 たとえば AdMob のフィル率を診断する自作スキルなら、名前と説明文の両方に「AdMob フィル率」という固有語を入れておくと、組み込みの汎用案内に持っていかれにくくなります。
私は、自作スキルの名前にプロジェクト固有の接頭辞を付ける運用に落ち着きました。たとえば複数アプリで共通の検証スキルなら、対象を名前に畳み込んでおく。名前を見ただけで守備範囲が分かると、依頼文を書く側も自然と発火しやすい言い回しになります。
組み込みを上書き・無効化するかの判断
固有語と命名で多くは解決しますが、それでも組み込みの Guide スキルが前に出てくる場面は残ります。このとき、組み込みを無効化するか、自作で上書きするかを決めます。
判断の軸はひとつだけです。「その依頼を、組み込みの汎用案内で十分に処理できるか」。十分なら、無理に上書きしない。自分の手順でなければ品質が崩れる依頼だけ、明示呼び出しを既定にするか、組み込みをそのワークスペースで無効化します。すべてを上書きすると、組み込みが改善されたときの恩恵を捨てることになります。
無効化は、ワークスペース単位で限定するのが安全です。全体で切ると、別プロジェクトで素直に使いたい場面まで巻き込みます。スキルは「共有したいもの」と「このリポでだけ効かせたいもの」を分けて持つと、衝突の管理がぐっと楽になります。
発火の記録を残しておく
最後に、どのスキルがどの依頼で発火したかを、軽くでよいので記録に残しておくことをおすすめします。応答の冒頭一行に発火したスキル名が出るなら、それを作業ログに転記しておくだけで十分です。
数日分たまると、衝突の傾向が見えてきます。「この言い回しだと必ず Guide が出る」という再現条件が分かれば、説明文を直すのも、依頼文の癖を直すのも、推測でなく観測に基づいて進められます。スキルの交通整理は、一度きりの設定ではなく、組み込みが更新されるたびに見直す運用だと捉えておくと、静かなずれに振り回されずに済みます。
次の一手として、いま頼りにしている自作スキルを一つ選び、その説明文に固有トリガー語を一行足してみてください。衝突がいちばん起きやすいスキルから整えるのが、いちばん手応えのある始め方です。