> 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/docs-as-code/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/docs-as-code/git-sync.md) のワークフローと相性がよく、リポジトリで変更を行ってコミットすれば、ドキュメントサイトは自動的に更新されます。 {% hint style="info" %} GitBook エディタで書くのが好みですか？ [GitBook Agent](/docs/documentation/ja-gitbook-documentation/gitbook-agent/overview.md) を使えば、GitBook を離れずに下書き、書き換え、レビュー、翻訳ができます。 {% endhint %} ## GitBook のスキルを AI エージェントに追加する AI コーディングアシスタントがパッケージベースのスキルをサポートしている場合に、このオプションを使ってください。 {% stepper %} {% step %} ### アクセストークンを作成するエージェントが GitBook とやり取りできるようにするには、 [アクセストークンを作成する](https://app.gitbook.com/account/developer) 必要があります。GitBook の開発者設定から作成してください。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 は、このトークンを使って、GitBook のスキルを使う際にエージェントを認証します。 {% endstep %} {% step %} ### GitBook のスキルをダウンロードする GitBook のスキルを使ってインストールする `npx skills add GitBookIO/gitbook-skills` 、アシスタントが対応している場合。ファイルを手動でプロジェクトにコピーするには、GitBook のスキルを [`gitbook-skills`](https://github.com/GitbookIO/gitbook-skills) リポジトリから取得してください。

スキル	説明	ダウンロード
`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. frontmatter（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 %} ## よくある質問

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

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

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

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

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

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

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

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

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

まず、よくある失敗箇所を確認してください。 * 閉じられていないカスタムブロック * frontmatter 内の無効な 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/docs-as-code/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.