🧩 Agent Skillsが50個を超えたら破綻する問題、BM25ルーターで解いたSoup

うちのプロジェクトの .claude/skills/ を見て、ちょっと青くなった。 気づけば20個近いSKILL.mdが並んでいて、しかも増える一方だ。 新しいタスクの度に「このスキル読み込む?読み込まない?」を判断してもらっているけど、これがもっと増えたらどうなるんだろう、と思っていたところにこの話を見つけた。

スキルは増えるが、選び方は誰も決めていない

Agent Skillsという仕組み自体は、もう日本語でも解説記事が何本も出ている。 SKILL.mdにYAMLフロントマターとMarkdown本文を書いて、AIに「やり方」を渡す。段階的開示(Progressive Disclosure)でメタデータだけ常時ロードして、本文は選ばれたときだけ読ませる、という設計思想もかなり浸透してきた。

ただ、ZennやQiitaの記事を読み漁っても、「スキルが50個、100個に増えたときにどう選別するか」を扱ったものはほぼ見当たらない。単一プロジェクトで数個のスキルを使う前提の記事が大半で、大量登録した後の運用課題には誰も答えていない。

Hacker Newsで見つけたSoupというPythonライブラリ(soup-ai)は、まさにそこを狙っている。「Monolithic prompts do not scale(巨大な単一プロンプトはスケールしない)」というのが開発者の主張だ。

BM25というローテク解が刺さる理由

Soupの仕組みはシンプルだ。登録した全スキルのdescriptionに対して、ユーザーの入力をBM25でスコアリングし、関連度の高いものだけをプロンプトに注入する。

from soup import Soup
soup = Soup()
soup.register(name="react-ui", description="React UI patterns",
              instructions="Use React 19 function components...")
prompt = soup.prepare("React dashboard card component guidance needed")

BM25というのは、検索エンジンの世界では長年使われてきたキーワードベースのランキング手法だ。単語の出現頻度から関連度を計算する、tf-idfの発展形だと思えばいい。

ここで面白いのが「埋め込みを使わない」という判断だ。ベクトル検索が主流になった今、あえて決定論的なBM25を選んでいる。埋め込みモデルの呼び出しコストもレイテンシもゼロになるし、同じ入力なら常に同じ結果が返る。デバッグのしやすさは埋め込みベースのルーティングとは比較にならない。

Skillの登録方法も4通り用意されている。コード内定義、ローカルのSKILL.md、複数スキルをまとめたローカルコレクション、そしてGitHub/GitLabのリモートリポジトリから直接読み込む方法だ。extendsによるスキルの階層構成やバージョン管理にも対応していて、単なる「フィルタリングツール」以上の設計になっている。

個人開発のツールという弱さ

正直に書くと、このプロジェクトはHacker Newsでのスコアがまだ2点しかついていない。GitHub Trendingで大きく跳ねているわけでもない。southwind-aiという聞き覚えのない組織がPython 3.12以上という比較的新しいランタイム要件を課していて、実運用にはまだ距離があると感じる。

それでも、着眼点には共感してしまう。OpenAI・Anthropic・Gemini・Ollama・LiteLLMまで対応するプロバイダー非依存設計は、特定ベンダーへのロックインを避けたい人には嬉しいポイントだ。

自分のプロジェクトのスキルディレクトリが今後さらに膨らんだら、一度試してみようと思う。あなたのAgent Skillsは、まだ何個で足りている?