contentstack-vibe-docs について
contentstack-vibe-docsは、Contentstackを使うAIエージェント向けのリファレンススキルです。ルーティング表とタスク別ガイドで必要な資料を絞り込み、全資料を読む手間を省きます。
主な機能
- 01タスク別のドキュメント案内
- 02APIとSDKのガイド
- 03Live Previewとフレームワークの解説
- 04セキュリティとトークンの指針
- 05ワークフローと拡張機能の資料
活用シーン
- 01タスクに合うAPIガイドの検索
- 02サイトへのLive Preview追加
- 03読み書きに使うトークンの選択
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/contentstack-vibe-docsを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
references/QUICK_REFERENCE.mdVERSIONS.mdreferences/api/content-management-api.mdgraphql-api.mdimage-delivery-api.mdrest-api.mdreferences/authentication/oauth.mdreferences/concepts/base-concepts.mddata-modeling-best-practices.mdlocalization.mdregions.mdreferences/examples/practical-examples.mdreferences/extensions/devhub-apps.mdlaunch.mdreferences/extensions/cli-plugins/commands.mdoverview.mdpublishing.mdreferences/frameworks/gatsby.mdnextjs.mdnuxt.mdreferences/live-preview/concepts.mdcsr-mode.mddebugging.mdssr-mode.mdvisual-builder.mdreferences/personalization/variants-and-personalize.mdreferences/sdk/delivery-sdk.mdreferences/security/roles-permissions.mdtokens-authentication.mdreferences/workflows/branches-aliases.md詳細
AI エージェント向け Contentstack ドキュメント
このスキルには、30 以上のリファレンスファイルに約 13,500 行が含まれています。**ルーティングテーブルを読み、実際に必要なファイルを 1～3 個選んだら、そこで止めてください。**すべてを読むことは避けてください。
ルーティングテーブル
| タスク | ファイル |
|---|---|
| コードパターンをすばやく検索する | QUICK_REFERENCE.md |
| Contentstack の基本 | concepts/base-concepts.md |
| コンテンツモデルの設計、参照・モジュラーブロック・グローバルフィールドの選択、タクソノミー | concepts/data-modeling-best-practices.md |
| ローカライゼーション、フォールバックチェーン、ローカライズできないフィールド | concepts/localization.md |
| リージョン、エンドポイント、リージョン対応ホスト | concepts/regions.md |
| コンテンツの取得（REST） | api/rest-api.md |
| コンテンツの取得（GraphQL） | api/graphql-api.md |
| 作成・更新・削除・公開、モジュラーブロックのスキーマ、CMA ヘッダー | api/content-management-api.md |
| 画像の変換、アセットフォルダー、アセットの制限、file_uid | api/image-delivery-api.md |
| TypeScript Delivery SDK | sdk/delivery-sdk.md |
| Live Preview の概要 | live-preview/concepts.md |
Live Preview の CSR（ssr: false） | live-preview/csr-mode.md |
Live Preview の SSR（ssr: true）、リクエストごとのファクトリー、ハッシュの分離 | live-preview/ssr-mode.md |
Visual Builder、編集タグ、addEditableTags、VB_EmptyBlockParentClass | live-preview/visual-builder.md |
| Live Preview / Visual Builder の問題をデバッグする | live-preview/debugging.md |
Next.js のパターン、Draft Mode、revalidateTag | frameworks/nextjs.md |
| Nuxt のパターン | frameworks/nuxt.md |
| Gatsby のパターン | frameworks/gatsby.md |
| 適切なトークンの選択（delivery/preview/management/authtoken/OAuth） | security/tokens-authentication.md |
| ロール、カスタム権限、チーム | security/roles-permissions.md |
| Auth.js v5（Next.js）での OAuth ログイン | authentication/oauth.md |
| Webhook：署名、イベントチャネル、リリースの集中発生 | workflows/webhooks.md |
| リリース：連携したアトミックなデプロイ | workflows/releases.md |
| ワークフローと公開ルール | workflows/content-workflows.md |
| ブランチとエイリアス：ダウンタイムなしのデプロイ | workflows/branches-aliases.md |
| 環境、公開、Sync API、レート制限 | workflows/environments-publishing.md |
| バリアントと Personalize | personalization/variants-and-personalize.md |
| CLI プラグイン — 概要とクイックスタート | extensions/cli-plugins/overview.md |
| CLI プラグイン — コマンド、フラグ、引数 | extensions/cli-plugins/commands.md |
| CLI プラグイン — 公開、テスト、トラブルシューティング | extensions/cli-plugins/publishing.md |
| Developer Hub アプリ（App SDK、UI の配置場所、API プロキシ） | extensions/devhub-apps.md |
| Contentstack Launch：デプロイ、環境の同期 | extensions/launch.md |
| 実用的なコードパターン | examples/practical-examples.md |
| パッケージのバージョン | VERSIONS.md |
一般的なタスクの組み合わせ
| シナリオ | ファイル（順番） |
|---|---|
| 新しい Next.js プロジェクト | base-concepts → delivery-sdk → nextjs |
| 新しい Nuxt プロジェクト | base-concepts → delivery-sdk → nuxt |
| Next.js に Live Preview を追加 | live-preview/concepts → live-preview/ssr-mode → nextjs |
| 既存のサイトに Visual Builder を追加 | live-preview/visual-builder |
| プレビューの不具合をデバッグ | live-preview/debugging |
| CRUD／移行スクリプトを作成 | content-management-api → security/tokens-authentication |
| ユーザーログイン付きのフルスタック構成 | delivery-sdk → nextjs → oauth |
| Webhook 駆動の再ビルド | workflows/webhooks → workflows/environments-publishing |
| ダウンタイムなしでコンテンツをデプロイ | workflows/branches-aliases → workflows/releases |
| 複数ロケールへの展開 | concepts/localization → workflows/environments-publishing |
| CI から Launch にデプロイ | extensions/launch → workflows/webhooks |
| レスポンシブ画像の最適化 | api/image-delivery-api |
| 簡単なスニペット | QUICK_REFERENCE.md |
選択のヒント
どの API を使いますか？ 公開済みコンテンツの読み取り → REST／GraphQL／Delivery SDK。コンテンツの書き込み → Content Management API。画像の変換 → Image Delivery API。
どの SDK を使いますか？
読み取り（フロントエンド／バックエンド）には @contentstack/delivery-sdk を使用します。書き込み（サーバー専用。フロントエンドでは使用しない）には @contentstack/management を使用します。
どの Live Preview モードを使いますか？
ssr フラグは、アプリのレンダリング戦略ではなく、CMS の iframe の更新方法を制御します。
ssr: false— postMessage。CMS が iframe にデータを送り、クライアントが再取得して、再読み込みせずに更新します。ssr: true—?live_preview=<hash>&entry_uid=...を付けて iframe を再読み込みします。サーバーはリクエストごとにパラメーターを読み取ります。
ssr: true の場合は、リクエストごとに新しい Contentstack クライアントを作成してください（ファクトリーパターン）。グローバルなクライアントを共有すると、同時に編集しているユーザー間でプレビュー状態が漏えいします。live-preview/ssr-mode.md を参照してください。
どのトークンを使いますか？
フロントエンドでの読み取り → Delivery Token（安全）。プレビューでの読み取り → Preview Token（安全）。サーバーでの書き込み → Management Token（フロントエンドでは絶対に使用しない）。ユーザーセッション → Authtoken または OAuth。詳しい選択手順は security/tokens-authentication.md を参照してください。
コーディング前に確認すること
実装する前に、開発者に以下を確認してください。
- リージョン（US、EU、AU、Azure NA/EU、GCP NA/EU）— すべてのエンドポイントに影響します。
- フレームワーク（Next.js、Nuxt、Gatsby など）— Live Preview モードを決定します。
- 環境（dev／staging／production）— Delivery Token の適用範囲を決定します。
- 環境変数に認証情報を設定していますか？ — 認証情報そのものを尋ねてはいけません。
セキュリティ（概要）
API キー、トークン、シークレットを尋ねたり、ログに記録したり、出力したり、ハードコードしたりしてはいけません。常に process.env.* の参照を使用してください。フロントエンドのコードで Management Token を使用してはいけません。開発者が本物のトークンを貼り付けた場合は警告し、ローテーションを勧めてください。詳細なルールは security/tokens-authentication.md を参照してください。
注意すべき点
- 1〜3 個のファイルを参照するのではなく、すべてのリファレンスファイルを読む。
- 認証情報をハードコードしたり、管理トークンをブラウザーに公開したりする。
@timbenniks/contentstack-endpointsを使わずにリージョンのホストをハードコードする。- Delivery SDK のパターンと Management SDK のパターンを混在させる。
- 1 つのクエリで REST と GraphQL のパターンを混在させる。
- SSR プレビューのリクエスト間で、モジュールレベルの Contentstack クライアントを共有する。
- 参照の公開で
api_version: 3.2を指定し忘れる。 .includeReference()を忘れ、参照が未定義になっている理由を調べる。X-RateLimit-Resetを無視して、429 に対してビジーループする。