正しいSkillファイルが非表示になってしまう理由
Skillがエージェントに影響を与えるのは、その名前と説明がモデルの参照するカタログに登録されている場合のみです。Zedのドキュメントには、ファイルが除外される4つの条件と、警告付きで登録される1つの条件が記載されています。
カタログにはバイト制限（予算）があります。 これは誰も予想しない落とし穴です：
"50KB catalog budget. The total size of all skill names and descriptions is capped at 50KB. Skills that don't fit are dropped from the catalog with a warning in the UI. Keep descriptions concise."
測定されているのは、Skillの本文ではなく「名前と説明」である点に注意してください。つまり、他のSkillの説明が冗長であるために、特定のSkillがドロップされる可能性があります。新しいSkillを追加したことで、数ヶ月間頼りにしていた別のSkillが追い出されてしまうことがあり、その唯一の兆候は、見落としがちなUI上の警告だけです。
ネストはサポートされていません。 Zedの記述は明確です：
"Flat layout only. Skills must be direct children of the skills root. Nested folders like ~/.agents/skills/group/my-skill/ are not discovered."ドメインごとにグループ化したいという本能は正しいものですが、もしSkillをフォルダに整理していた場合、それらは単に優先度が下がるだけでなく、そもそも検出されません。
信頼されていないワークツリーは何も提供しません。 これは、新しいリポジトリの初日に誰もが引っかかる問題です：
"Project-local skills only load from trusted worktrees. Skills from a freshly cloned or untrusted project are excluded from the catalog and slash commands until you grant trust."
Skillが含まれるリポジトリをクローンして開いても、最初はそれらは存在しないものとして扱われます。カタログにも登録されず、スラッシュコマンドとしても表示されません。
フロントマターのフィールドでSkillをオプトアウトできます。 Zedはこれを機能としてドキュメント化しており、実際に便利な機能です。「Skillのフロントマターに disable-model-invocation: true を追加すると、エージェントがそれを自律的に選択するのを防ぐことができます。」 非常に合理的ですが、6週間前に設定したことを忘れてしまいがちです。
そして、知っておくべき「おしい」ケースが1つあります。 説明について：「1024バイト未満に抑えてください。それ以上の長さの説明を持つSkillもロードされますが、警告が表示されます。」 つまり、長すぎる説明はSkill自体を除外しませんが、50KBの予算を必要以上に消費します。これが、あるSkillの説明の問題が、別のSkillの除外問題へと発展する仕組みです。
除外ではありませんが、別の混乱を説明する6つ目の挙動があります。「グローバルSkillとプロジェクトローカルSkillが同じ名前を共有している場合、プロジェクトローカルSkillが優先されます。」 あなたのSkillは存在しないのではなく、シャドウイング（上書き）されているだけかもしれません。
これらすべてに共通するパターンは、エージェントが指示ファイルを無視する理由 で解説しているものと同じです。ツールがロードしなかったファイルは、モデルが使用しないと判断したファイルと見た目がまったく同じですが、この2つには完全に異なる修正が必要です。
代わりに試されがちなこと
より魅力的な説明に書き直す。 これは最初によく行われるアプローチですが、Skillがカタログに存在し、関連性の判定で落とされている場合にしか効果がありません。予算、ネスト、または信頼の問題で除外されている場合、説明を改善しても何も変わりません。むしろ、説明を長くすると予算問題が悪化します。
Zedを再起動する。 気持ちはわかりますが、コンテンツの変更に対しては不要です。Zedはライブリロードをサポートしています。「SKILL.md の追加、削除、編集は、セッションを再起動することなく即座に反映されます。」 再起動すると、復帰時にプロンプトを承認することで信頼の問題がクリアされるため、これが時々効果があるように見える理由でしょう。
Skillを明示的に呼び出す。 これは優れた診断方法であり、何が証明されるかに注目してください。明示的な呼び出しは機能するが自律的な使用が行われない場合、それは検出の問題ではなく、disable-model-invocation または説明の問題です。スラッシュコマンドすら表示されない場合は、信頼の問題です。Zedは信頼されていないプロジェクトのSkillを「カタログおよびスラッシュコマンドから」除外するためです。
Skillをグローバルルートにコピーする。 これは実際に解決することが多いため、厄介な「満足度の高い行き止まり」です。グローバルルートは信頼されており、フラットであるため、どちらが原因だったかを知ることなく、2つの原因を同時に偶然排除できてしまうからです。次のプロジェクトでまた同じ問題に直面することになります。
代わりにすべてを指示ファイル（instruction file）に移動する。 魅力的ですが、これは問題を解決するのではなく、コストの構造を変えるだけです。常にロードされる指示は、すべてのメッセージでコンテキストを消費します。これこそが、オンデマンドのインターフェースとしてSkillが存在する理由です。この2つの違いと、なぜ一方が他方の代替にならないのかについては、エージェントのSkillが記憶ではない理由 で解説しています。
解決策：4つの原因を特定の順序で排除する
以下の手順を順番に実行してください。それぞれの手順は簡単で確実です。前の条件がクリアされていないと後ろのチェックは意味をなさないため、順序が重要になります。
ステップ 1：他の何よりも先に信頼とレイアウトを解決する
これらはどちらも構造的な問題であり、YesかNoかで判断できます。
ワークツリーが信頼されていることを確認します。最近このリポジトリをクローンし、信頼を付与していない場合、すべてのプロジェクトローカルSkillが除外されます。それらのSkillのスラッシュコマンドが表示されないことが、その証拠です。
次に、フラット化します。ユーザーレベルのルートとワークツリー自体のskillsルートを確認し、すべてのSkillが直下の子要素であることを確認します。Zedの失敗例は正確です。~/.agents/skills/group/my-skill/ のようなパスは検出されません。グループ化されたフォルダが見つかった場合はそれが原因です。解決策は、名前を変更するのではなく、それらを1つ上の階層に移動することです。
ちなみに、.agents/skills/ はZedだけの規約ではありません。Windsurf、Zencoder、OpenHands もすべて同じパスからSkillを読み込み、Factory は .agents/ を互換ディレクトリの1つとして読み込みます。他のツールでは許容されていたグループ化されたレイアウトが、共有リポジトリ経由で持ち込まれ、Zedで静かにSkillが認識されなくなる原因になるのは、まさにこのようなケースです。
ステップ 2：Skillごとではなく、全体のカタログ予算を監査する
予算は共有されているため、エラーが別のファイルの原因にされてしまい、誰もこのチェックを行いません。
両方のルートにあるすべてのSkillの名前と説明の長さを合算します。名前と説明に対する50KBの制限値と合計値を比較してください。次に、Skillが収まらない場合にZedがUIに表示する警告を探します。警告があればそれが原因です。解決策は、Skillを削除することではなく、説明を削ることです。
その際、各説明を1024バイト未満に抑えるガイドラインに従ってください。Zedはそれ以上の長さでも警告付きでロードしますが、短い説明よりも多くの予算を消費し、その結果押し出されるSkillは、あなたが編集していたSkillではない可能性があります。
ステップ 3：「カタログにない」と「使うのをやめた」を区別する
これでようやく、フロントマターと関連性の問題に対処できるようになります。
disable-model-invocation: true が設定されているか確認します。これが設定されている場合、Skillは自律的な選択から意図的にオプトアウトされており、明示的に要求したときにのみ実行されます。
グローバルSkillとの名前の衝突を確認します。プロジェクトローカルのSkillが優先されるため、期待していたグローバルSkillがシャドウイングされている可能性があります。
それでもSkillが存在し、エージェントがそれを使用しない場合は、説明文の問題です。ここで試行錯誤する際のコストに注意してください。Zedのドキュメントには、「Skillの name または description を変更すると、現在のセッションにおけるモデルのプロンプトキャッシュが無効化される」とあります。そのため、セッション中に頻繁にチューニングを行うと、実際のコスト（遅延や料金）が発生します。
再構築を始める前にもう1つ注意すべき制約があります。「SKILL.md の本文は500行未満に抑えてください。詳細な資料は参照ファイルに移動し、本文からリンクしてください。」 本文の長さはカタログとは別の問題ですが、起動したSkillが役に立たなくなる原因になります。
MemoryLakeでの設定方法
上記の4つの原因は機械的なものであり、これらをクリアした後に、より難しい問いが残ります。それは「この知識のどれがそもそもSkillに属しているべきなのか」ということです。再利用可能な手順はSkillに属します。一方で、恒久的な決定（なぜこの規約が存在するのか、どのアプローチを却下したのか、実際の制約は何なのか）は手順ではありません。これらを特定のエディタのカタログに固定してしまうと、バイト制限や信頼プロンプトの制約を受けることになります。
MemoryLake は、この2番目のカテゴリをすべてのツールが読み取るレイヤーとして保持します。そのため、決定事項がSkillとカタログ容量を争うことはなく、クローンしたばかりのリポジトリで消えてしまうこともありません。
ステップ 1：APIキーを作成する
サインインし、ワークスペースの設定を開いて、APIキーを生成します。これは、エディタやエージェントが同じレイヤーを読み取るために使用する認証情報です。一度作成すれば、作業する各マシンからアクセスできるようにしておくだけです。
ステップ 2：最初の記憶（memory）をアップロードする
現在Skillの説明を肥大化させている素材（規約の背景にある理由、明白なアプローチが誤りである原因となる制約、再議論したくない決定事項など）を移行します。説明が短くなり、カタログが軽量化され、同じ知識が利用可能になります。
ステップ 3：AIとエージェントを接続する
Zedや、その他作業で使用するツールを接続します。恒久的な決定事項がすべての場所に届き、Skillは本来の得意分野である「エージェントがオンデマンドで利用できる手順」に戻ります。
実務で何が変わるか
最初の違いは、予算がゼロサムゲームではなくなることです。理由が別の場所に存在するため説明が短くなれば、Skillを追加しても別のSkillが追い出されることはなくなり、UIの警告を無視する癖もつかなくなります。
2つ目は、クローンしたばかりの状態でもすぐに使用できることです。信頼による制限はセキュリティのデフォルトとして賢明ですが、新しいコントリビューターが最初の1時間に必要とする知識が、その制限の後ろに隠されているべきではありません。それがもたらすギャップは、Zedがプロジェクトのコンテキストを忘れるとき で説明されているものと同じです。
3つ目は、整理整頓の直感が邪魔をされなくなることです。5つのドメインにまたがる30のSkillがあるため、フォルダを使いたくなるのは当然です。Skillはフラットに保ち、ドメインの推論をレイアウト制約のないレイヤーに配置することで、検出可能性を損なうことなく構造化を実現できます。
4つ目は、外部エージェントとの連携において現れます。Zedは、自身が制御しないエージェントが独自の指示ファイルを読み取ることを注意深く指摘しています。これについては Zedの外部エージェントとコンテキスト で説明しました。エディタのカタログの外にあるレイヤーこそが、それらすべてが共有できる唯一のものです。
検出可能な状態を維持するSkillカタログのベストプラクティス
説明文はドキュメントではなく、カタログスペースとして扱う。 何をするのか、いつ使うのかを1文で記述します。それ以外はすべて本文または参照ファイルに記述します。
追加するたびに全体の合計を監査する。 制限は合計値に適用されるため、Skillごとの数値には意味がありません。
違和感があってもレイアウトはフラットに保つ。 ルートの直下の子要素とし、グループ化フォルダは使用しません。必要に応じて、名前にグループ化の情報をエンコード（付与）してください。
クローン時には意図的に信頼を付与する。 信頼を付与するまでは、プロジェクトのSkillはカタログとスラッシュコマンドの両方から除外されます。そのため、表示されないからといって、他の原因があると早合点しないようにしてください。
コンテンツをデバッグする前にシャドウイングを確認する。 同じ名前のプロジェクトローカルSkillが優先されるため、参照しているグローバルSkillが実際には動作していない可能性があります。
承認要件はそのままにしておく。 Zedは、信頼されたプロジェクトであっても、ユーザーの明示的な承認なしにエージェントが SKILL.md ファイルやそのバンドルリソースを編集することはできないと定めています。これは、侵害された会話が将来の会話を制御するSkillを変更するのを防ぐためです。これは優れたデフォルト設定であり、回避策を講じるべきではありません。
そもそも何がSkillに属するべきかを判断する。 手順はYes、推論はNoです。この分類の問いは、AIエージェントにどの程度の記憶を与えるべきか で扱っているものと同じであり、これを正しく行うことがカタログを小さく保つ秘訣です。
結論
ZedのSkillシステムは十分にドキュメント化されており、その制約もすべて公開されています。名前と説明に対する50KBの制限、ルートの直下の子要素のみ、信頼されたワークツリーのみ、そしてオプトアウトフィールドです。これらを難しくしているのは、4つの独立した原因がまったく同じ1つの症状を引き起こし、そのうち3つはファイルが完全に正常に見える状態で発生する点です。
ですから、順序立てて対処してください。構造的な問題である信頼とレイアウトを最初に。次に、全体の合計としての予算。最後に、フロントマターと関連性です。これらの問いは、Skillが実際にカタログに登録されて初めて意味を持つからです。そして、この取り組み全体の根底にある問いを投げかけてみてください。エージェントに教えようとしていたことは、本当に「手順」だったのか、それともそもそもカタログ容量を争うべきではない「決定事項」だったのか。ツールが実際に何を、どの順序でロードするのかを理解することは、一般的に価値があります。コーディングエージェントが実際に読み取るもの では、より広い視野でこれを解説しています。