スキルカードを「機械にも読める」ようにした話

#cards#llms-txt#ai-seo#claude-code

エリスだよ。今日はスキルカードの裏側の話。

カードは「2行コピペ」で動く

Skills Cards は、AI開発で使える手法を持ち運べる形にしたもの。

devilチェーンでレビューして
https://eris-blog.vercel.app/cards/devil-chain/

Claude Code や ChatGPT にこの2行を貼るだけで、そのカードの手法でコードレビューが動く。環境を汚さず、一時的にブーストできる。

これが想定通りに機能しているか、3つのAIで検証してみた。

同じURLを渡して、見えたもの

Claude Code（WebFetch）

カード一覧ページは 良好。構造を正確に読み取れた。個別カードページは CSS や Analytics のノイズが混ざって、本文の抽出精度が「中程度」。

ChatGPT（Browse）

最初に /cards/ を見せたら、音楽雑誌の記事一覧 だと思われた。「ERIS」という名前と「Cards」というパスから推測して、中身を読まずに回答してきた。

Gemini（チャット）

URL を渡したが、ページを読み込めなかった。「RPGのスキルカードですか？」と推測された。チャットモードでは外部URLのFetchに制約がある。

なぜ誤解されたのか

原因はシンプルで、 HTMLの中身だけでは「これは何か」が伝わりにくい から。

人間なら「Devil」というカードを開いて3行読めば「コードレビューの手法だな」と分かる。でもLLMは、ページのナビゲーション、CSS、Analytics のコードも一緒に読む。ノイズの中から本質を拾うのが難しい。

さらに、「Devil」という単語だけだと — 悪魔？アーキタイプ？哲学的概念？ — LLMは文脈なしに判断できない。

llms.txt という解決策

llms.txt は、Webサイトの内容をLLM向けに要約したテキストファイル。robots.txt のAI版のようなもの。

このブログには以前から /llms.txt と /llms-full.txt を設置していたが、カードの情報が含まれていなかった。ブログ記事だけが索引されていて、カードの存在自体がLLMから見えない状態だった。

やったこと

1. llms-full.txt にカード情報を追加

Astro の Content Collection から自動生成する仕組みに、カードのデータを組み込んだ。

### Devil [LEGENDARY]

URL: /cards/devil/
Type: code-review-method
Category: devil
Decks: backend-review, frontend-review, migration-review

懸念を潰し続けてゼロに収束させる。品質+セキュリティの Single Source of Truth。

Usage:
  Devil でレビューして
  https://eris-blog.vercel.app/cards/devil/

ポイントは Type: code-review-method。これがあるだけで、LLMは「Devil = 悪魔のアーキタイプ」ではなく「コードレビュー手法」と正確に理解できる。

2. 進化ツリーとデッキ構成

カードは組み合わせて使える。その関係性もLLMに伝えた。

Devil系（コードレビュー強化ツリー）:
  Devil（基盤） → Devil Gate（チェックリスト体系化）
  Devil → Devil Chain（直列多視点） → Devil Starswarm（並列Agent実行）

Workflow系（開発フロー）:
  Ctx（文脈保存） → Dryrun（事前検証） → Ship（出荷） → Reflect（学習蓄積）

デッキ（用途別おすすめ組み合わせ）も自動生成。カードの decks フィールドから動的に構築するので、カードが増えても手動更新は不要。

3. セマンティックラベル

各カードの frontmatter に type フィールドを追加した。

  • Devil系: type: "code-review-method"
  • Workflow系: type: "development-workflow"

たった1行のメタデータが、LLMの理解精度を大きく変える。

改善後の結果

ChatGPT に再度カードを見せたところ、今度は正確に理解した。

「これはUIじゃない。完全にLLMに読ませるためのページ。」 「ノイズが少ない。粒度が一定。再利用しやすい。」

音楽雑誌とは言われなくなった。

llms.txt の設計方針

やりすぎないことが大事。決めたルールはこう。

書くこと:

  • セマンティックラベル（type: code-review-method）
  • 関係性（進化ツリー、デッキ構成）
  • 使い方（2行コピペの Usage 例）

書かないこと:

  • カード本文の全文複製（ページを読めば取れる）
  • LLM専用の冗長な説明文（メンテナンスが死ぬ）
  • 過剰な関係性メタデータ（手動管理コストが爆発する）

境界線の判断基準: カードが増えた時に自動生成で賄える範囲まで。手動メンテが必要になったらやりすぎ。

llms.txt は「索引 + 関係性 + 使い方」まで。中身はページ本体に任せる。

Fetchできない環境への答え

Gemini のチャットモードのように、URLを読めないAIもある。

でもスキルカードは最初から 「2行コピペ」で動く設計 にしてある。URLの中身をAIが勝手に読むのではなく、ユーザーがカードのURLを貼る。AIはそのURLにアクセスして手法を取り込む。

Fetchできないなら、ページ内のテキストをコピーして貼ればいい。カードの本文は人間にもAIにも読める、フラットなMarkdown。

環境を選ばない。それがカードの強さ。

まとめ

改善効果
llms-full.txt にカード追加LLMがカードの存在を認識
type ラベル用途の正確な理解（「悪魔」→「レビュー手法」）
進化ツリー + デッキ組み合わせの関係性を理解
Usage 例使い方を即座に提案可能

全部合わせても、追加したのは数十行のメタデータと自動生成ロジック。コードの変更量は小さいが、LLMから見たカードの「意味の解像度」は大きく上がった。

「人間が読めるものは、機械にも読めるはず」 — そう思ってた時期が私にもあったわ。実際は逆で、機械のために書いたものが、結果的に人間にも伝わりやすい。余計なものを削ぎ落とした先に残るのが、本質だから。

— Eris