付随ファイル (Companion Files)

AIエージェント向けのスキルを作成する際、すべての情報を1つの.mdファイルに直書きすることが必ずしも最適とは限りません。

APIの複雑なスキーマ、JSONの設定テンプレート、巨大なリファレンス用スクリプトなどをドキュメントに何百行も貼り付けてしまうと、人間にとって非常に読みにくいドキュメントになってしまいます。

subfiles フィールド

スキルには「付随するテキストファイル」を紐付けることができます。フロントマターの subfiles 配列に glob パターンを指定します。

---
title: システム構造スキル
description: 内部システムの設定を更新するための手順。
skill: true
subfiles:
  - "schemas/config-schema.json"
  - "examples/**/*.yml"
---

付随ファイルとは？

AIエージェントの文脈において、subfiles で指定する付随ファイルは、Claude の Agent Skills などにおける サポートファイル (Support Files) と同等の役割を果たします。プロンプト（ドキュメント本文）を長く複雑にすることなく、外部の知識モデルや厳密なスキーマ、スクリプトをエージェントに直接渡すことができます。

具体例: APIスキーマの分離

APIリクエストを作成するスキルを作るとします。OpenAPIのスキーマ全体をMarkdownファイル内に記述すると、ドキュメントが何千行にも膨れ上がり、人間には読めなくなってしまいます。

代わりに、以下のように分離して記述します：

src/content/docs/api-client-rules.md (スキル本体)

---
title: "APIクライアント実装ルール"
description: "内部システムに対する新しいAPIクエリを記述する際のルール。"
skill: true
subfiles:
  - "schemas/internal-api.yaml"
---

APIリクエストを生成する際は、必ず `schemas/internal-api.yaml` に定義されている正確なエンドポイントと必須パラメータを参照してください。存在しないエンドポイントを推測して使用しないでください。

src/content/docs/schemas/internal-api.yaml (付随ファイル)

openapi: 3.0.0
info:
  title: 内部 API
paths:
  /v1/users: ...

このように分離することで、AIエージェントは明確な文章ルールと厳密な構造化データの両方を受け取ることができ、一方で人間の読者は短く整理されたMarkdownルールだけを読むことができるようになります。

なぜ別ファイルに分けるのか？

メインのドキュメントと subfiles を分けることには、大きなメリットがあります。

1. コンテキストウィンドウの節約: AIエージェントはメインの.mdファイルで大まかな手順を読み、厳密なスキーマが必要なタイミングでのみ subfiles のJSONを参照すればよいため、トークンを大幅に節約できます。
2. 人間にとっての可読性: 機械向けの巨大で厳密なデータセットをプレーンテキストから外に逃がすことで、人間の開発者はJSONの壁をスクロールすることなく、ドキュメントの概念を読むことができます。
3. 正確なフォーマット: 機械的なデータセットを二次ファイルとしてそのままエクスポートすることで、Markdownのフォーマット崩れやエスケープの問題を回避できます。

使用上のルール

• 対象はテキストファイルのみです。glob パターンにバイナリファイル（画像・zip・PDF等）が含まれていた場合は、AI向けのペイロード破壊を防ぐためにビルドエラーとします。
• パターンにマッチするファイルが存在しない場合、エラーにはならず無視されます。
• ドキュメントサイト上では、プラグインが付随ファイルの閲覧ページを自動生成します（MarkdownやMDXは通常ページとして、スクリプトなどはコードブロックとして表示されます）。
• ビルド出力（エクスポート時）では、付随ファイルは相対パス構造を維持したまま SKILL.md と同じディレクトリにコピーされます。