> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/ja-gitbook-documentation/getting-started/ai-documentation/ai-coding-assistants-and-skillmd.md). # Agent スキル GitBook は提供しています [スキルファイル](https://github.com/GitbookIO/gitbook-skills/tree/main) AI コーディングアシスタントに、GitBook のドキュメントを正しく編集する方法を教えます。Claude Code、Cursor、Codex、または別の外部コーディングアシスタントを使う場合は、GitBook スキルを追加して、エージェントが GitBook の構文、ブロック、設定ファイルを扱えるようにしてください。これは次とよく合います [Git Sync](/docs/documentation/ja-gitbook-documentation/getting-started/git-sync.md) ワークフロー — リポジトリで変更を加え、コミットすると、ドキュメントサイトが自動で更新されます。 {% hint style="info" %} GitBook エディタで書くのが好みですか？次を使ってください [GitBook Agent](/docs/documentation/ja-gitbook-documentation/gitbook-agent/what-is-gitbook-agent.md) GitBook を離れずに、コンテンツの下書き、書き換え、レビュー、翻訳を行えます。 {% endhint %} ## AI エージェントに GitBook スキルを追加する AI コーディングアシスタントがパッケージベースのスキルをサポートしている場合は、このオプションを使用してください。 {% stepper %} {% step %} ### アクセストークンを作成するエージェントが GitBook とやり取りできるようにするには、 [アクセストークンを作成する](https://app.gitbook.com/account/developer) 必要があります。GitBook は、このトークンを使って、GitBook スキルを扱う際にエージェントを認証します。 {% endstep %} {% step %} ### GitBook スキルをインストールするこのスキルは [`gitbook-skills`](https://github.com/GitbookIO/gitbook-skills) リポジトリの一部です。次のコマンドを実行して、GitBook スキルをプロジェクトに直接インストールしてください： {% code expandable="true" %} ```bash npx skills add GitBookIO/gitbook-skills ``` {% endcode %} {% endstep %} {% endstepper %} ## GitBook スキルをローカルに追加するアシスタントがパッケージベースのスキルをサポートしていない場合は、GitBook のスキルをダウンロードしてください。 {% stepper %} {% step %} ### アクセストークンを作成するエージェントが GitBook とやり取りできるようにするには、 [アクセストークンを作成する](https://app.gitbook.com/account/developer) 必要があります。GitBook は、このトークンを使って、GitBook スキルを扱う際にエージェントを認証します。 {% endstep %} {% step %} ### GitBook スキルをダウンロードする GitBook スキルを次の方法でインストール `npx skills add GitBookIO/gitbook-skills` アシスタントが対応している場合に使用してください。ファイルを手動でプロジェクトにコピーするには、次の [`gitbook-skills`](https://github.com/GitbookIO/gitbook-skills) リポジトリから GitBook スキルを取得してください。

スキル	説明	ダウンロード
`configure-site`	GitBook のドキュメントサイト全体を作成・維持します。	GitHub
`write-docs`	GitBook のドキュメントページを作成、執筆、編集、整形します。	GitHub
`write-openapi`	OpenAPI/Swagger の API リファレンスドキュメントを作成、設定、構成、トラブルシュートします。	GitHub
`build-integration`	GitBook 用のカスタム統合を構築します。	GitHub
`cr-create`	GitBook の変更リクエストを作成し、コンテンツをプッシュし、レビューを依頼し、コメントに対応します。	GitHub
`cr-review`	GitBook の変更リクエストをレビューし、変更点を要約し、コメントし、承認するか、変更を依頼します。	GitHub

{% hint style="warning" %} GitBook に新機能が追加されたら、必ずローカルのリポジトリを最新の `SKILL.md` ファイルで更新することを忘れないでください。 {% endhint %} {% endstep %} {% endstepper %} ## GitBook スキルの使用方法 {% prompt description="Scaffold a Git-synced docs site from a folder of markdown" %} ```markdown GitBook スキルを使って、この markdown のフォルダを Git Sync で支えられた GitBook ドキュメントサイトに変換してください。 1. ドキュメントフォルダを読み、サイト構成（スペース、ページツリー、SUMMARY.md ナビゲーション）を提案してください。何か書く前に見せてください。 2. リポジトリを GitBook のモノレポ構成（各スペースごとに README.md + SUMMARY.md）で足場を作り、コミットしてください。 3. サイトとスペースを作成し、GitBook UI で私が行う 1 つの手順、つまり各スペースを Git Sync でそれぞれのディレクトリに接続するための、正確なコピペ用手順を教えてください。 4. 同期の設定が完了したら、サイト構成が計画どおりか確認してください。 ``` {% endprompt %} {% prompt description="Upgrade a plain markdown page into a polished GitBook page" %} ```markdown GitBook スキルを使って、このページを GitBook のリッチブロックで書き換えてください。今はただの Markdown です。 1. ページを読み、どこを改善するか教えてください。多言語のコードサンプル → タブ、順を追う手順 → ステッパー、注意書き → ヒント、「自分の進みたい道を選ぶ」コンテンツ → カード。 2. フロントマター（title、description、icon）を含め、正しい GitBook 構文で変更を適用してください。 3. 文章はそのままで構いません — 声色ではなく構成を改善してください。 4. GitBook でレンダリングされた後に、私が再確認すべき点を列挙してください。 ``` {% endprompt %} {% prompt description="Generate an API reference from an OpenAPI spec" %} ```markdown GitBook スキルを使って、OpenAPI 仕様からドキュメント内に API リファレンスセクションをセットアップしてください。 1. 仕様を見つける（または存在しない場合はコードベースから生成するのを手伝う）し、検証してください。 2. SUMMARY.md で GitBook の OpenAPI ブロックを使って、エンドポイントページを自動生成するように設定してください。エンドポイントページは手作業で書かないでください。仕様が唯一の正しい情報源です。 3. リソースグループごとに短い概要ページを追加してください。 4. 仕様の不足（説明、例、レスポンススキーマの欠落）で、レンダリングされたリファレンスが弱くなる箇所を指摘してください。 ``` {% endprompt %} ## FAQ

SKILL.md には何が含まれていますか？

`SKILL.md` AI コーディングアシスタントが、GitBook コンテンツを正しく作成、編集、整形するために必要なコンテキストを提供します。含まれるもの： * カスタムブロックの完全な構文リファレンス。 * 設定ファイル形式。たとえば `.gitbook.yaml`, `SUMMARY.md`、そして `.gitbook/vars.yaml`. * フロントマターのオプション、レイアウト制御、変数、式、決定表、よくある落とし穴。

AI が生成したコンテンツはどうテストすればよいですか？

AI アシスタントが生成したコンテンツは、必ずレビューしてテストしてください。スキルファイルで学習したアシスタントを使う場合： * カスタムブロックが GitBook で正しくレンダリングされることを確認してください。 * すべての内部リンクが機能することを確認してください。 * フロントマターが有効な YAML であることを確認してください。 * 変数が正しいスコープを参照していることをテストしてください。

アシスタントが SKILL.md を使っているかどうすれば分かりますか？

GitBook ページをどのように整形するか説明するように依頼してみてください。 GitBook のブロック、フロントマター、変数、または次のようなファイルに言及しているなら `SUMMARY.md`、スキルは読み込まれています。一般的な Markdown だけで答える場合は、プロジェクトルールを確認してアシスタントを再読み込みしてください。

なぜアシスタントは GitBook 固有の構文を無視するのですか？

通常、これはスキルファイルが読み込まれていないか、ルールが十分に具体的でないことを意味します。アシスタントが `SKILL.md` をリポジトリのルートから読み込むか、プロジェクトの指示で GitHub の URL を使用していることを確認してください。アシスタントが指示をキャッシュする場合は、ルールを追加または更新した後にセッションを再起動してください。

アシスタントが無効な GitBook コンテンツを生成したらどうなりますか？

まず、よくある失敗箇所を確認してください： * 閉じていないカスタムブロック * フロントマター内の無効な YAML * 壊れた変数参照 * ページ構成と一致しないリンクコミットする前に、必ず GitBook で出力を確認してください。

それでもアクセストークンは必要ですか？

エージェントが GitBook と直接やり取りする場合は、アクセストークンが必要です。あなたの [開発者設定](https://app.gitbook.com/account/developer). ローカルでファイルを編集しているだけなら `SKILL.md`、アシスタントを GitBook のワークフローや API に接続するまでは不要かもしれません。

スキルが古いように見える場合は？

ローカルの `SKILL.md`を更新するか、アシスタントを GitHub のソースに戻してください。チームがファイルの一部をカスタムルールにコピーしている場合は、それらも更新してください。

--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://gitbook.com/docs/documentation/ja-gitbook-documentation/getting-started/ai-documentation/ai-coding-assistants-and-skillmd.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.