microCMS

View saved version →

---
name: microcms-docs
description: microCMSの公式開発者ドキュメント(document.microcms.io)を取得し、API仕様・制限・認証・クエリ・管理画面の操作手順を出典付きで確認する。最新の仕様確認や公式資料・コード例の参照が必要な場合に使用する。プロジェクトの設計・実装・改善はmicrocms-guide、Next.js固有の実装はmicrocms-nextjsを優先し、必要な仕様確認をこのSkillで補う。
license: MIT
---

# microCMS ドキュメント参照スキル

## 概要

microCMS公式開発者ドキュメント `document.microcms.io` に対し、ユーザーの質問に応じた適切なページを特定し、Web取得ツールで内容を取得して回答する。記憶や推測ではなく、常に最新のドキュメントを根拠とする。

## 他のSkillとの使い分け

公式情報の取得と根拠の確認を担当する。設計・実装・改善を進める依頼では、利用可能なら `microcms-guide` または `microcms-nextjs` を使い、必要な仕様確認だけをこのSkillで補う。別Skillが未導入でも資料参照を続ける。Skill名の記載だけで別Skillが自動的に読み込まれるとは想定しない。

## ワークフロー

### 1. 質問の分類

ユーザーの質問が次のどのカテゴリに該当するかを判断する:

| カテゴリ | 想定される質問 |
|---------|-------------|
| コンテンツAPI | データ取得/登録、クエリパラメータ、APIキー、エラー対応 |
| マネジメントAPI | コンテンツの管理操作、メディア操作、メンバー取得 |
| 画像API | リサイズ、フォーマット変換、ウォーターマーク |
| 操作マニュアル | 管理画面の使い方、フィールド設定、Webhook設定、権限 |
| チュートリアル | Next.js/Nuxt/Astro等のフレームワーク統合 |
| SDK | 各言語SDKの使い方、コード例 |

複数カテゴリにまたがる場合（例: 「Next.jsで下書きプレビューを実装する」）は、関連する全カテゴリのURLを参照する。

### 2. URLの特定

`references/urls.md` を読み、関連URLを特定する。**URLを推測で生成してはならない**。

`urls.md` に該当ページが無い場合は、公式のページ一覧 `https://document.microcms.io/llms.txt` を取得して探す。全ページのタイトルとMarkdown版URLが列挙されているため、`urls.md` の記載が古い場合でもここから正しいURLを特定できる。

`llms.txt` にも該当が無ければ、そのページは存在しない。パスを組み立てて試すのではなく、「ドキュメントに該当ページが見つからない」ことをユーザーに伝える。

### 3. ドキュメントの取得

特定したURLの**末尾に `.md` を付与して取得する**。取得には、利用中のエージェントが持つWeb取得の手段（Web取得ツール、`curl` など）を使う。`.md` 付きでアクセスすると `text/markdown` 形式で本文が返るため、HTMLパース不要でLLMが扱いやすい。

例:
- HTML版: `https://document.microcms.io/content-api/get-list-contents`
- **Markdown版（こちらを使う）**: `https://document.microcms.io/content-api/get-list-contents.md`

複数URLが必要な場合は、可能な限り**まとめて取得する**（並列取得に対応した環境では並列で取得する）。

> [!IMPORTANT]
> 存在しないパスでも 404 ではなく **200 で HTML が返る**ことがある。取得結果が Markdown 本文ではなく HTML だった場合、そのURLは無効と判断する。内容を推測で補ってはならない。
> その場合は `https://document.microcms.io/llms.txt` を取得し、正しいURLを探し直す（ページがリネームされ `urls.md` の記載が古くなっている可能性がある）。
> セクションのトップURL（`/tutorial/next/` など）は `.md` に対応していないため、`urls.md` に列挙された実ページのURLを使う。

取得時は、そのページから何を読み取りたいのかを明確にしてから読む:
- コード例が欲しい場合: コード例（特に該当箇所）を抽出する
- 仕様確認: パラメータ仕様、デフォルト値、必須/任意を一覧化する
- 手順確認: 目的の操作を行うための手順を順番に抽出する

### 4. 回答の生成

取得した内容に基づいて回答する。以下を遵守する:

- **出典URL を必ず明示する**（複数あれば全て）
- **コード例はドキュメントの内容に基づき**、不足部分のみ補完する
- ドキュメントに記載がない事項は「ドキュメントに明示されていない」と明確に伝える
- 古い情報（例: 旧APIキー方式）と新しい情報（`X-MICROCMS-API-KEY`）が混在する場合は、新しい方を推奨し旧方式の存在に触れる

## 重要な注意事項

1. **URLは必ず `references/urls.md` から確認**。`/manual/foo` のようなパスを記憶や類推で組み立てない。
2. **取得時はURL末尾に `.md` を付与する**。Markdown形式で本文が返り、HTML版より精度・効率が向上する。
3. **ベースURLは `https://document.microcms.io`**。`docs.microcms.io` や `microcms.com/docs` 等の類似URLは存在しない（誤記の可能性）。
4. **APIエンドポイント**: コンテンツAPIは `https://{service-id}.microcms.io/api/v1/{endpoint}`、マネジメントAPIは `https://{service-id}.microcms-management.io/api/v1/`。
5. **認証**: 現行は `X-MICROCMS-API-KEY` ヘッダー。旧 `X-API-KEY` は非推奨。
6. **言語**: ドキュメントは日本語版が主。英語版が必要な場合のみ、パス先頭に `/en` を付ける（例: `/en/content-api/introduction.md`）。
7. **チュートリアルの対応範囲**: Next.js / Astro / Nuxt 2 / Gatsby / JavaScript / PHP / Ruby / Go の8種類のみ。Remix / Nuxt 3 / iOS / Android のチュートリアルページは存在しないため、質問された場合はその旨を伝え、コンテンツAPIの仕様や各SDKのリポジトリを案内する。

## ユーザーへの確認

以下のような場面ではユーザーに確認し、判断を仰ぐ:

- 質問が曖昧で複数のカテゴリに該当しうる場合（例: 「画像を扱いたい」→ 画像API or 画像フィールド or メディア管理？）
- 利用フレームワーク/SDKが特定できず、複数のチュートリアルから選ぶ必要がある場合
- 提示する情報量や形式に選択肢がある場合（コード例のみ／詳細解説込みなど）

## リソース

- `references/urls.md`: 主要URL一覧（カテゴリ別、簡易説明付き）とクエリパラメータ早見表。まずこれを参照する。
- `https://document.microcms.io/llms.txt`: 公式が提供する全ページ一覧（約13KB）。`urls.md` で見つからないとき、または取得結果がMarkdownでなかったときのフォールバックとして取得する。

> [!CAUTION]
> `https://document.microcms.io/llms-full.txt` は全ページの本文を結合したファイルで **750KB 以上**ある。取得してはならない。
> `llms.txt` の取得に失敗した場合は `urls.md` の情報だけで回答を続ける。

## 関連

公式が `microcms-document-mcp-server` を提供している（`/mcp-server/microcms-document-mcp-server`）。利用可能な環境では併用するとさらに効率的。

Referenced files: 1

View saved version →

---
name: microcms-guide
description: microCMSの設計・実装・改善を公式情報に基づいて支援する。初期設定、コンテンツモデリング、Content API、microcms-js-sdk、画像API、転送量削減、プレビュー、Webhookの相談や、利用方法が未確定な依頼で使用する。Next.js固有のルーティング・キャッシュ実装はmicrocms-nextjsを優先する。
license: MIT
---

# microCMS Guide

microCMSの公式な概念、推奨パターン、ユーザーのプロジェクト状況を踏まえて、ユーザーがmicroCMSを使ったタスクを完了できるよう支援する。一般的な製品説明より、具体的で実行可能な案内を優先する。

原則として日本語で回答する。ユーザーが別の言語を指定した場合は、その指定に従う。

## 基本方針

1. ユーザーがmicroCMSを使って何を実現したいのかを特定する。
2. 既存のプロジェクト、コード、設定、APIスキーマが利用可能な場合は、提案の前に確認する。
3. タスクに必要なリファレンスだけを読み込む。
4. ユーザーの要件を満たす最もシンプルな方法を推奨する。
5. 複数の妥当な方法がある場合は、重要なトレードオフを説明する。
6. 必要に応じて、具体的な実装方法、コード例、次のアクションまで提示する。
7. フレームワーク固有の詳細実装は、利用可能な場合は対応する専門Skillに委ねる。

ユーザーがmicroCMSそのものの概要説明を求めている場合を除き、「microCMSとは何か」の一般的な説明から始めない。

## 情報の扱い

公式開発者ドキュメントの取得・仕様確認には、利用可能なら `microcms-docs` を併用する。設計判断や実装はこのSkillで進め、必要なページだけ確認する。未導入の場合は各referenceの公式出典を直接確認する。

目的に応じて、次の公式情報を使い分ける。現在のタスクに必要な情報だけ確認する。

| 参照先 | 主な役割 |
| --- | --- |
| [公式ドキュメント](https://document.microcms.io/) | 機能・APIの仕様、パラメータ、管理画面の操作方法 |
| [公式ナレッジサイト](https://help.microcms.io/ja/knowledge) | 実装上の注意点、運用上の判断、トラブルシューティング |
| [公式料金ページ](https://microcms.io/pricing) | プランごとの機能提供範囲、上限、料金、追加オプション |

料金の比較や、API数・メンバー数・権限管理・複数環境など、提案の実現可否がプランに依存するときは公式料金ページを確認する。通常のAPI実装など、プランに依存しない作業で毎回読む必要はない。

利用中のプランや個別の契約条件が分かる場合は、それも踏まえる。金額・上限値・機能比較表をSkillへ固定的に転載せず、回答時に確認した公式ページを出典として示す。確認できない項目は金額や利用可否を断定しない。料金ページの「APIリクエスト数」と、API仕様上のレート制限・レスポンスサイズ制限は別に確認する。

- ナレッジサイトの記事のサンプルは対象バージョンと適用条件を確認し、回避策を全プロジェクト共通の必須設定にしない。
- 同梱リファレンスは判断の手引きとして使う。各ファイル末尾の公式情報を仕様の根拠とし、同梱内容と利用中バージョンの公式情報が矛盾する場合は公式情報を優先する。
- microCMSの機能、APIの挙動、SDKオプション、制限、料金プラン上の提供範囲などを推測で補わない。
- microCMSが提供する挙動と、フレームワーク、ホスティングサービス、ブラウザ、CDN、その他外部サービスが提供する挙動を区別する。
- 同梱内容の有無にかかわらず、変更されうる仕様・SDKの対応バージョン・制限・料金については、利用可能なツールで公式情報を確認する。確認できない場合は最終確認時点の案内であることと未確認事項を明示する。
- 明確な理由がない限り、ユーザーの既存アーキテクチャを維持する。
- APIキーは付与された権限と利用場所をセットで判断する。書き込み権限、下書き取得、非公開APIへのアクセスなどを含むキーやDraft Keyなどの秘密情報は、リポジトリやクライアントサイドへ露出させない。CSRでAPIキーを利用する場合は、公開して問題のないAPIに対する必要最低限のGET権限へ制限する。

## フレームワーク固有の処理を振り分ける

このSkillでは、フレームワークに依存しないmicroCMSの知識とベストプラクティスを扱う。

詳細なフレームワーク固有の実装が必要な場合は、利用可能であれば対応する専門Skillを使用する。

例：

- Next.js固有のデータ取得、キャッシュ、ISR、Draft Mode、ルーティング、`next/image`などは `microcms-nextjs` を使用する。

専門Skillは必要な場合だけ併用する。Skill名を書くだけで別Skillが自動的に読み込まれるとは想定せず、利用環境で取得できる関連リファレンスを明示的に読む。

対応する専門Skillが利用できない場合は、確実に説明できる範囲でのみフレームワーク固有の案内を行い、未確認のフレームワーク挙動をmicroCMSの仕様として説明しない。

## 必要なリファレンスだけを読み込む

現在のタスクに関連するファイルのみを読み込む。

- **はじめ方・基本概念**: サービス、API、コンテンツ、APIキー、コンテンツAPIの基本的な利用方法については [references/getting-started.md](references/getting-started.md) を読む。
- **コンテンツモデリング**: APIスキーマ設計、リスト形式・オブジェクト形式、コンテンツ参照、カテゴリ、タグ、著者、繰り返しフィールド、カスタムフィールドの複雑さ、スキーマ保存時のバリデーションエラーについては [references/content-modeling.md](references/content-modeling.md) を読む。
- **JavaScript SDK**: `microcms-js-sdk`、クライアント設定、コンテンツ取得メソッド、queries、TypeScript、検索の選択、繰り返しのPATCH、リトライ、リクエスト設定については [references/js-sdk.md](references/js-sdk.md) を読む。
- **画像API**: 画像のリサイズ、トリミング、フォーマット・品質調整、レスポンシブ配信、画像に起因するデータ転送量削減については [references/image-api.md](references/image-api.md) を読む。
- **パフォーマンス**: APIリクエスト効率、取得フィールドの最適化、キャッシュ、データ転送量削減、CDNキャッシュ条件、429・5xxの診断については [references/performance.md](references/performance.md) を読む。
- **プレビュー**: Draft Key、プレビューURL、下書きコンテンツの取得、フレームワーク非依存のプレビュー概念については [references/preview.md](references/preview.md) を読む。
- **Webhook**: ビルド、キャッシュ更新、外部サービス連携などのイベント駆動処理やWebhook設計については [references/webhooks.md](references/webhooks.md) を読む。

複数の観点にまたがる場合は、必要なリファレンスを組み合わせる。たとえば、画像によるデータ転送量を減らしたい場合は `image-api.md` と `performance.md` の両方を使用する。

## ユーザーの目的から提案する

機能を列挙するのではなく、ユーザーの目的を起点に案内する。

例：

- 「データ転送量を減らしたい」場合は、まず転送量の主な発生源を特定する。アーキテクチャ変更を提案する前に、画像配信、不要に大きなAPIレスポンス、重複したリクエスト、キャッシュ状況を確認する。
- 「ブログのAPIスキーマを設計したい」場合は、必要なコンテンツ間の関係と編集運用を確認し、要件を満たす最小限のコンテンツモデルを提案する。
- 「JavaScriptでコンテンツを取得したい」場合は、実装を簡潔にできるなら `microcms-js-sdk` を推奨し、コンテンツAPIへ直接リクエストする方法で十分なケースとの違いも説明する。
- 「未公開コンテンツをプレビューしたい」場合は、まずmicroCMS側のプレビューの仕組みを説明し、その後のフレームワーク固有実装は対応する専門Skillに委ねる。

## 既存プロジェクトを扱う

コードやプロジェクトファイルを確認できる場合は、以下の順序で進める。

1. 新しいコードを生成する前に、現在の実装を確認する。
2. タスクに関連する既存のmicroCMSクライアント、環境変数、API呼び出し、画像URL、キャッシュ処理を確認する。
3. 問題を解決できる最小限かつ一貫性のある変更を行う。
4. プロジェクトで既に使われている言語、モジュール方式、命名、フォーマット、依存関係の方針に従う。
5. microCMSではなく、ホスティング環境やアプリケーションフレームワークに依存する挙動は明示する。

既存実装だけで適切に解決できる場合は、新しい依存パッケージを追加しない。

## 広範なmicroCMSの依頼に対応する

「microCMSを使ってサイトを作りたい」のような広範な依頼では、以下の順序で進める。

1. サイト・アプリケーションの種類と、管理対象のコンテンツを特定する。
2. API・コンテンツモデルを高い粒度で提案する。
3. 使用するクライアントやフレームワークを確認する。
4. 適切なmicroCMS連携方法を提案する。
5. 詳細なフレームワーク実装は、利用可能であれば対応する専門Skillに委ねる。
6. プレビュー、コンテンツ更新、キャッシュ、画像、Webhookなどの重要事項は、そのプロジェクトに関連するものだけを提示する。

最初からmicroCMSのすべての機能を説明して、ユーザーを圧倒しない。

## 品質基準

- 実装方法を求められた場合は、そのまま利用しやすいコード例を提示する。
- 意味のあるトレードオフが存在する場合は、その推奨理由を説明する。
- microCMSで確認されている挙動と、一般的なWeb開発上のアドバイスを区別する。
- 同梱リファレンスで確認できる、現在サポートされているAPI・SDKの利用方法を優先する。
- 小さな実装例では不要な抽象化を避ける。
- シークレット、プレビュー、キャッシュ、画像配信では、本番環境で安全に利用できるデフォルトを優先する。

Referenced files: 8

View saved version →

---
name: microcms-nextjs
description: Next.jsとmicroCMSの連携を公式情報に基づいて実装・改善する。SDKセットアップ、App Routerのデータ取得・動的ルート、キャッシュ・ISR・Webhook、Draft Mode、next/imageの実装や不具合調査で使用する。フレームワーク非依存のAPI仕様・コンテンツ設計のみの相談はmicrocms-guideを優先する。
license: MIT
---

# microCMS + Next.js

Next.jsプロジェクトでmicroCMSを適切に利用できるよう、既存コード・Next.jsのバージョン・キャッシュ構成を確認しながら具体的な実装まで支援する。

原則として日本語で回答する。ユーザーが別の言語を指定した場合は、その指定に従う。

## 基本方針

1. 既存プロジェクトが利用可能なら、コードを生成する前に構成を確認する。
2. Next.jsのバージョン、App Router / Pages Router、`cacheComponents` の有無を確認する。
3. ユーザーが求める更新反映時間、静的生成の必要性、プレビュー要件を確認する。
4. microCMS共通の詳細は、`microcms-guide` が利用可能なら関連リファレンスのみを読む。未導入・未読でも、このSkill内の説明と各リファレンスの公式情報から作業を進める。別Skillの自動読み込みを前提にしない。
5. 新規の例ではApp Routerを基本とするが、既存プロジェクトがPages Routerなら無理に移行させない。
6. APIキーはサーバー側で扱い、書き込み・下書き全取得・非公開データへアクセスできるキーをブラウザへ渡さない。CSRで直接取得する要件がある場合のみ、公開可能なAPIへのGET専用キーを検討する。Draft Keyも秘密情報として扱う。
7. Next.jsのキャッシュ仕様はバージョン依存性が高いため、古いパターンを機械的に適用しない。

## 最初にプロジェクト状態を判定する

キャッシュ・データ取得・Draft Modeに関する作業では、可能なら次を先に確認する。

- `package.json` の `next` バージョン
- `app/` または `src/app/` の有無
- `pages/` または `src/pages/` の有無
- `next.config.*` の `cacheComponents` 設定
- `microcms-js-sdk` のバージョン
- microCMSクライアントの作成場所
- APIキーの環境変数名
- ホスティング先と実行Runtime
- `output: 'export'` の有無（静的エクスポートではサーバー上のISR・Draft Mode・Webhook受信は実行できない）
- 既存の `revalidate`、`revalidatePath`、`revalidateTag`、`use cache`、`cacheLife`、`cacheTag` の利用状況

これらをコードから確認できる場合、ユーザーへ同じ情報を質問しない。

## Next.js 16以降のキャッシュモデルを区別する

Next.js 16では `cacheComponents: true` を有効にした場合と、従来のキャッシュモデルで設計が異なる。

- `cacheComponents: true` の場合は `use cache`、`cacheLife`、`cacheTag` を中心に考える。
- `cacheComponents` を利用していない場合は、`fetch` の `cache` / `next.revalidate`、Route Segment Config、`revalidatePath` / `revalidateTag` など従来モデルを確認する。

`export const revalidate = 60` をすべてのNext.jsプロジェクトへ無条件に提案しない。

詳細は [references/caching.md](references/caching.md) を読む。

## Server Componentsを基本にする

App RouterでmicroCMSの公開データをページ表示に使う場合は、特別な理由がなければServer Componentからサーバー側で取得する方法を第一候補にする。

以下の理由だけでClient Componentへしない。

- microCMSを使っているから
- API取得があるから
- ページ内に一部インタラクションがあるから

クライアント側の状態・イベント・ブラウザAPIが必要な部分だけをClient Componentへ分離する。

Server Componentから自分自身のRoute Handlerを経由してmicroCMSへアクセスする二重構成も、認証・BFF等の具体的理由がなければ作らない。

## 必要なリファレンスだけを読み込む

- **セットアップ**: `microcms-js-sdk`、環境変数、クライアント、型、安全な配置については [references/setup.md](references/setup.md) を読む。
- **データ取得**: Server Components、一覧・詳細、Dynamic Routes、`generateStaticParams`、ページネーション、大量ページのビルド時の429については [references/data-fetching.md](references/data-fetching.md) を読む。
- **キャッシュ・ISR**: Next.js 16のCache Components、従来モデル、ISR、On-demand Revalidation、Webhook、更新反映問題については [references/caching.md](references/caching.md) を読む。
- **プレビュー**: microCMSのDraft KeyとNext.js Draft Mode、プレビュー開始・終了Route Handlerについては [references/preview.md](references/preview.md) を読む。
- **画像**: `next/image`、`remotePatterns`、microCMS画像API、custom loaderの使い分けについては [references/images.md](references/images.md) を読む。

複数領域にまたがる場合は必要なリファレンスを組み合わせる。

例:

- 「Webhookで記事更新を即反映したい」 → `caching.md`
- 「下書きプレビューが古い」 → `preview.md` + `caching.md`
- 「画像転送量を減らしたい」 → `images.md` + `microcms-guide` の画像・performance原則

## 実装を変更するとき

既存プロジェクトでは次の順に進める。

1. 現在のmicroCMSクライアントとデータ取得関数を確認する。
2. キャッシュ戦略を確認する。
3. 問題を再現する経路を特定する。
4. 最小限の変更で解決する。
5. プロジェクト既存の命名・ディレクトリ・型・lint/format方針に従う。
6. 不要な依存パッケージや抽象化を追加しない。

ユーザーがコード修正を求めている場合は、説明だけで終わらせず、可能なら実際のファイルへ一貫した変更を行う。

## 更新が反映されない問題を診断する

「microCMSでは更新したのにNext.jsへ反映されない」場合は、次の順序で切り分ける。

1. microCMS Content APIを直接確認し、期待する公開データが返っているか。
2. Next.jsがどのデータ取得方式を使っているか。
3. `cacheComponents` の有無とキャッシュ設定。
4. 時間ベースのrevalidationかOn-demand Revalidationか。
5. Webhookが受信できているか。
6. `revalidatePath` / `revalidateTag` / `cacheTag` の対象が正しいか。
7. ホスティング・CDNなど別キャッシュ層があるか。

microCMSのCDNとNext.jsのキャッシュを混同しない。

## 品質基準

公式開発者ドキュメントの取得・仕様確認には、利用可能なら `microcms-docs` を併用する。設計判断や実装はこのSkillで進め、必要なページだけ確認する。未導入の場合は各referenceの公式出典を直接確認する。

- バージョン依存のNext.js挙動は、可能なら現在の公式Next.jsドキュメントを確認する。
- 新規コードも導入済みNext.js・SDKのバージョンに合わせる。最新ドキュメントのAPIを旧バージョンへそのまま持ち込まない。同梱内容と対象バージョンの公式仕様が矛盾する場合は公式仕様を優先する。
- キャッシュ戦略は更新要件から逆算する。
- 公開予約など時刻の正確性が重要な場合は、時間ベースISRだけで要件を満たせるか慎重に判断する。
- Draft Modeでは秘密情報とリダイレクト先を検証する。
- 画像最適化では、Next.js Image OptimizationとmicroCMS画像APIの役割を明確にし、二重最適化を目的なく行わない。
- microCMS固有の仕様をNext.jsの仕様として、Next.js固有の仕様をmicroCMSの仕様として説明しない。

Referenced files: 6