> 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).

# エージェントスキル

Claude Code、Cursor、Codex などの AI コーディングアシスタントに GitBook スキルを追加すると、GitBook のページ、サイト、ワークフローを操作できるようになります。

GitBookを初めて設定しますか？エージェントの参照先を [GitBookを設定する](https://gitbook.com/docs/documentation/ja-gitbook-documentation/setup.md) に変更してください。

GitBook は、次の場所で一連のスキルを公開しています。 [gitbook-skills](https://github.com/GitbookIO/gitbook-skills) リポジトリです。これらのスキルは、AI コーディングアシスタントが GitBook ドキュメントを扱う方法を学べるようにします。ページの作成、サイトの設定、OpenAPI リファレンス、変更リクエスト、インテグレーションに対応しています。Claude Code、Cursor、Codex、その他のコーディングアシスタントを使用する場合は、スキルを追加すると、エージェントが GitBook の構文、ブロック、設定ファイルを正しく扱えるようになります。

これは [Git Sync](https://gitbook.com/docs/documentation/ja-gitbook-documentation/docs-as-code/git-sync.md) のワークフローと相性がよく、リポジトリで変更を加えてコミットすると、ドキュメントサイトが自動的に更新されます。

{% hint style="info" %}
GitBook エディターでの執筆をご希望ですか？ [GitBook Agent](https://gitbook.com/docs/documentation/ja-gitbook-documentation/gitbook-jento/overview.md) を使えば、GitBook を離れることなく、コンテンツの下書き、書き換え、レビュー、翻訳ができます。
{% endhint %}

## AI エージェントに GitBook スキルを追加する

AI コーディングアシスタントがパッケージベースのスキルに対応している場合は、この方法を使用してください。

{% stepper %}
{% step %}

### GitBook MCP に接続する

次のようにファイルの編集のみを行うスキルは `write-docs`、GitBook の認証を必要としません。GitBook とやり取りするスキル（以下を含む）は `configure-site`, `write-openapi`, `cr-create`、そして `cr-review` — は次を使用してください [GitBook MCP](https://gitbook.com/docs/documentation/ja-gitbook-documentation/docs-as-code/gitbook-mcp.md) 接続を使用します。この接続では、ブラウザーで OAuth 認証を行います。

次の場所で発行する個人用アクセストークン [開発者設定](https://app.gitbook.com/account/developer) は、REST API を直接呼び出す場合にのみ必要です。 `cr-create` と `cr-review` REST API を使用するため、トークンが必要です。 `configure-site` と `write-openapi` まず MCP を優先し、MCP に接続されていない場合はトークンにフォールバックします。
{% endstep %}

{% step %}

### GitBook スキルをインストールする

スキルは [`gitbook-skills`](https://github.com/GitbookIO/gitbook-skills) リポジトリにあります。次のコマンドを実行して、プロジェクトにインストールしてください。

{% code expandable="true" %}

```bash
npx -y skills add GitbookIO/gitbook-skills -y
```

{% endcode %}

両方がそろっていないと `-y` フラグを指定しない場合、インストーラーは入力を待ちます。
{% endstep %}
{% endstepper %}

## GitBook スキルをローカルに追加する

アシスタントがパッケージベースのスキルに対応していない場合は、GitBook のスキルをダウンロードしてください。

{% stepper %}
{% step %}

### GitBook スキルをダウンロードする

次のコマンドでGitBookのスキルをインストールできます。 `npx -y skills add GitbookIO/gitbook-skills -y` お使いのアシスタントが対応している場合に実行してください。

ファイルを手動でプロジェクトにコピーするには、次のリポジトリから取得してください。 [`gitbook-skills`](https://github.com/GitbookIO/gitbook-skills) リポジトリ。

<table><thead><tr><th width="156.67578125" valign="top">スキル</th><th width="455.33203125" valign="top">説明</th><th valign="top">ダウンロード</th></tr></thead><tbody><tr><td valign="top"><code>write-docs</code></td><td valign="top">GitBook形式のMarkdownページを作成・編集します。</td><td valign="top"><a href="https://github.com/GitbookIO/gitbook-skills/tree/main/skills/write-docs">GitHub</a><br></td></tr><tr><td valign="top"><code>configure-site</code></td><td valign="top">REST APIを使って、GitBookサイトを最初から最後まで作成・設定します。</td><td valign="top"><a href="https://github.com/GitbookIO/gitbook-skills/tree/main/skills/configure-site">GitHub</a><br></td></tr><tr><td valign="top"><code>write-openapi</code></td><td valign="top">GitBookでOpenAPIリファレンスドキュメントを作成・公開します。</td><td valign="top"><a href="https://github.com/GitbookIO/gitbook-skills/tree/main/skills/write-openapi">GitHub</a></td></tr><tr><td valign="top"><code>cr-create</code></td><td valign="top">REST API を使って GitBook のドキュメントレビューの流れを進めます。変更リクエストを作成し、コンテンツをプッシュしてレビューを依頼し、コメントに対応します。</td><td valign="top"><a href="https://github.com/GitbookIO/gitbook-skills/tree/main/skills/cr-create">GitHub</a></td></tr><tr><td valign="top"><code>cr-review</code></td><td valign="top">REST API を使って GitBook の変更リクエストをレビューします。変更リクエストを見つけて変更内容を要約し、コメント、承認、または変更をリクエストします。</td><td valign="top"><a href="https://github.com/GitbookIO/gitbook-skills/tree/main/skills/cr-review">GitHub</a></td></tr><tr><td valign="top"><code>build-integration</code></td><td valign="top">GitBook のインテグレーションを構築、開発、公開します。カスタムブロック、ContentKit UI、イベント、OAuth を扱います。</td><td valign="top"><a href="https://github.com/GitbookIO/gitbook-skills/tree/main/skills/build-integration">GitHub</a></td></tr></tbody></table>

{% hint style="warning" %}
GitBook に新機能が追加されたら、ローカルのスキルも忘れずに更新してください。
{% 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 で私が行う唯一の手順である、Git Sync を使って各スペースを対応するディレクトリに接続するための、正確ですぐにコピーして使える手順を教えてください。
4. 同期が設定されていることを確認したら、サイト構造が計画どおりか確認してください。
```

{% endprompt %}

{% prompt description="Upgrade a plain markdown page into a polished GitBook page" %}

```markdown
GitBookのスキルを使って、このページを書き直してください。現在はプレーンなMarkdownですが、GitBookのリッチブロックを使用してください。

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 %}

## FAQ

<details>

<summary>GitBook のスキルには何が含まれていますか？</summary>

リポジトリ内のスキル [gitbook-skills](https://github.com/GitbookIO/gitbook-skills) は、GitBook のコンテンツを正しく作成、編集、書式設定するために、AI コーディングアシスタントに必要なコンテキストを提供します。

`write-docs` には、次の内容が含まれます：

* カスタムブロックの構文を網羅したリファレンス。
* 次のファイルを含む設定ファイルの形式。 `.gitbook.yaml`, `SUMMARY.md`および `.gitbook/vars.yaml`.
* frontmatterのオプション、レイアウト制御、変数、式、判断表、よくある落とし穴。

その他のスキルでは、サイトの設定、OpenAPI リファレンス、変更リクエスト、インテグレーションについて扱います。

</details>

<details>

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

AI アシスタントが生成したコンテンツは、必ず確認してテストしてください。GitBook スキルでトレーニングされたアシスタントを使う場合は、次の点に注意してください。

* カスタムブロックがGitBookで正しくレンダリングされることを確認します。
* すべての内部リンクが機能することを確認します。
* frontmatterが有効なYAMLであることを確認します。
* 変数が正しいスコープを参照していることをテストします。

</details>

<details>

<summary>アシスタントが GitBook スキルを使っているかどうかは、どうすればわかりますか？</summary>

GitBookのページをどのように書式設定するか、アシスタントに説明を求めてください。

GitBook ブロック、フロントマター、変数、または次のようなファイルに言及していれば、 `SUMMARY.md`スキルが読み込まれています。

一般的な Markdown だけで回答する場合は、スキルがインストールされていることを確認し、アシスタントを再読み込みしてください。

</details>

<details>

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

これは通常、スキルが読み込まれていないか、ルールが十分に具体的でないことを意味します。

GitBook スキルがインストールされており、アシスタントがそれらを読み取れることを確認してください。

アシスタントが指示をキャッシュする場合は、スキルを追加または更新した後にセッションを再起動してください。

</details>

<details>

<summary>アシスタントが無効なGitBookコンテンツを生成した場合は、どうすればよいですか？</summary>

まず、よくある問題の箇所を確認してください。

* 閉じられていないカスタムブロック
* frontmatterの無効なYAML
* 壊れた変数参照
* ページ構成と一致しないリンク

コミットする前に、必ずGitBookで出力を確認してください。

</details>

<details>

<summary>引き続きアクセストークンが必要ですか？</summary>

接続 [GitBook MCP](https://gitbook.com/docs/documentation/ja-gitbook-documentation/docs-as-code/gitbook-mcp.md) し、スキルが GitBook との通信を必要とするときは OAuth でサインインしてください。これで、ほとんどの `configure-site` と `write-openapi`.

スキルが REST API を直接呼び出す場合（ `cr-create` や `cr-review`など）、または MCP が接続されていない場合は、個人アクセストークンが必要です。トークンは [開発者設定](https://app.gitbook.com/account/developer).

次の方法でローカルのファイルだけを編集する場合は、 `write-docs`トークンも MCP 接続も必要ありません。

</details>

<details>

<summary>スキルが古くなっているように見える場合は？</summary>

インストール済みのスキルを更新するか、GitHub のソースをアシスタントに再度指定してください。

チームでスキルの一部をカスタムルールにコピーした場合は、それらも更新してください。

</details>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://gitbook.com/docs/documentation/ja-gitbook-documentation/docs-as-code/ai-coding-assistants-and-skillmd.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
