| 症状 | 最も可能性の高い原因 | 変更する点 |
|---|---|---|
| そのために書いた作業でも、スキルが一度も発動しない。 | 説明文が作者の語彙で書かれており、実際の依頼の言い回しと一致していません。 | 同僚が使う言葉で説明文を書き直し、「いつ使うか」を明示します。自分ではなく他人の言い方で作業を頼んで確認してください。 |
| 関係のない作業でも発動してしまう。 | 説明文が広すぎるか一般的すぎて、想定よりはるかに多くの依頼と一致しています。 | 対象の成果物や状況に絞ります。一般的な活動名ではなく、形式、システム、文書の種類を明記してください。 |
| 読み込まれるのに、最初の部分しか守られない。 | 本体が長く、重要な指示がモデルに不要な背景の後ろに埋もれています。 | 背景を削ります。詳細は references/ に移し、本体には手順、判断点、出力の形だけを残してください。 |
| 自分は何も変えていないのに、セッションごとに挙動が変わる。 | 導入済みの別のスキルが同じ判断を指示しており、どちらが勝つかが安定していません。 | 互換性マップを確認し、どちらか一方を外します。1 つの仕事に対する 2 つの方法論は冗長化ではなく衝突です。 |
| スキルをまとめて入れてから、セッションが重く感じる。 | 導入済みのスキルはすべて起動時にメタデータ分を支払い、肥大した本体は起動時にもう一度支払います。 | 誰も発動させないスキルを削除し、目安として 500 行を超えるものは分割します。コストはセッションごとに効いてきます。 |
| 自分の環境では動くのに、同僚の環境では動かない。 | 相手側に導入されていないか、スキルが宣言していない自分の環境の何かに依存しています。 | 実際の環境要件を compatibility に書き、自分だけが持つツール、パス、資格情報を前提にしていないか確認してください。 |
| 検証は通るのに、まったく何も起きない。 | 検証が見るのはファイルであって設置ではありません。フォルダー名が name と一致していないか、エージェントが読み込む場所に置かれていない可能性があります。 | フォルダー名が name と完全に一致していることを確認し、次に、使っているエージェントが実際にスキルを読む場所へ導入されているか確認します。 |
これらがすべて静かに失敗する理由
一致しなかったスキルはエラーではありません。エージェント側では何も起きていないからです。メタデータが読まれ、作業と一致せず、実行はそのまま続きました。だからこの種の問題は数週間生き延び、だからこそ毎回まず説明文を見るべきなのです。
確認する順序
上から順に見れば数分で済みます。下から、つまり本体の書き直しから始めるのが、半日を失う典型です。
- エージェントが読む場所に置かれていて、フォルダー名は name と一致しているか。
- 説明文に、他人がこの作業に使う言葉が含まれているか。
- 説明文は「何をするか」だけでなく「いつ使うか」も書いているか。
- 同じ判断を指示している別のスキルがないか。
- 重要な部分が埋もれない程度に本体は短いか。