メインコンテンツまでスキップ

Kuroco Skills の使い方

Kuroco Skills は、Kuroco 開発を支援する Agent Skills パッケージです。 Kuroco の API 連携、コンテンツ管理、フロントエンド統合、バッチ処理などに関するベストプラクティスを AI エージェントに提供し、Kuroco 開発の生産性を向上させます。

Agent Skills は SKILL.md を中心としたファイルベースの標準仕様で、Claude Code をはじめ複数の AI エージェントで利用できます。エージェントは起動時に各スキルの name と description だけを読み込み、関連する依頼が来たときに本文を読み込みます（プログレッシブディスクロージャー）。そのため、インストールしただけではコンテキストをほとんど消費しません。

Kuroco AI アーキテクチャ​

Kuroco は AI 連携のために以下のインターフェースを提供しています。

コンポーネント種類説明
管理画面Web UI管理者向けの Kuroco 管理画面
Admin APIREST APIAPI 経由の管理操作（/direct/rcms_api/admin_api/）
Admin MCPMCP サーバAdmin API の MCP サーバ（/direct/rcms_api/admin_mcp/）、Bearer トークン認証
Client APIREST APIフロントエンドアプリ向けの公開 API（/rcms-api/{id}/）
Client APIMCP サーバClient API の MCP サーバ (/rcms-api/{id}/mcp)
Client CLICLI ツールClient API のラッパー CLI（kuroco-client）

AI エージェントから管理操作を行う場合は、Admin MCP を使用してください。MCP 対応クライアント（Claude Code、Claude Desktop など）に直接登録でき、OAuth によるスコープ／読み取り専用のアクセス制御を利用できます。

Client CLI は、独立して使用可能なスタンドアロンのコマンドラインツールです。

Kuroco Skills とは​

Kuroco Skills をインストールすると、AI エージェントが Kuroco に関する質問に対して、正確で具体的なコード例やベストプラクティスを提示できるようになります。 以下の 13 個のスキルが含まれています。

スキル説明
kuroco-docsKuroco 公式ドキュメントの検索・参照
kuroco-app-builderアプリ・サイトをゼロから構築するワークフロー（モックファースト → コンテンツ定義 → API → 実データ接続 → デプロイ）
kuroco-api-contentAPI 設計・認証（Cookie / 動的・静的アクセストークン）、CORS、コンテンツ CRUD、フィルタークエリ
kuroco-frontend-integrationVite / Nuxt.js / Next.js 統合、SPA/SSG/SSR、認証実装、KurocoFront へのデプロイ
kuroco-server-processingSmarty プラグイン・構文リファレンス（205 プラグイン）、バッチ処理、Webhook、トリガー
kuroco-admin-mcpAdmin MCP（管理 MCP サーバ）への接続設定、OAuth / CIMD 認証、スコープ、ツール利用
kuroco-content-structure-designコンテンツ構造の設計判断（コンテンツ定義の分割、JSON 項目によるフィールド圧縮、マスタデータの表現、分類の持ち方、ext_slug の命名方針）
kuroco-content-structure-creationMCP ツールによるコンテンツ定義（TopicsGroup）の作成、フィールドタイプリファレンス
kuroco-auth-design会員認証・権限の設計判断（会員グループ、登録フロー、アクセス制限のスコープ、パスワードポリシー、エンタープライズ SSO / SCIM 連携）
kuroco-external-integration-design外部システム連携方式の設計判断（直接呼び出し / プロキシ / 取り込み、シークレット・トークン管理）
kuroco-api-performance-reviewAPI パフォーマンス・利用料の調査（API 解析、キャッシュ設定レビュー、改善提案）
kuroco-security-auditセキュリティ設定の読み取り専用診断（API セキュリティ、CORS、IP 制限、権限、トークン）
kuroco-spec-writer実設定からの仕様書生成（読み取り専用）。項目表・ER 図・API 一覧などを Markdown + Mermaid で出力

各スキルの詳細は「Kuroco Skills リファレンス」を参照してください。

事前準備: Claude Code のインストール​

Claude Code で Kuroco Skills を使用する場合は、Claude Code をインストールします。Codex や claude.ai で使用する場合、この手順は不要です。

注意

Claude Code はデスクトップ版（CLI）でのみ動作確認を行っています。Web 版（claude.ai）での動作は未検証です。

macOS の場合​

ネイティブインストーラー（推奨）または Homebrew でインストールします。

# ネイティブインストーラー（推奨、自動更新あり）
curl -fsSL https://claude.ai/install.sh | bash

# または Homebrew
brew install --cask claude-code

インストール後、ターミナルで claude を実行すると Claude Code が起動します。

Windows の場合​

ネイティブインストーラー（推奨）、WinGet、または WSL でインストールします。

# PowerShell（推奨、自動更新あり）
irm https://claude.ai/install.ps1 | iex

# または WinGet
winget install Anthropic.ClaudeCode

インストール後、ターミナル（PowerShell またはコマンドプロンプト）で claude を実行すると Claude Code が起動します。

注記

Windows ではネイティブ（Git Bash が必要）と WSL の両方に対応しています。WSL 2 の使用が推奨されています。詳細は Claude Code 公式ドキュメントを参照してください。

その他のインストール方法については Claude Code セットアップガイドを参照してください。

インストール方法​

利用するクライアントに応じて選んでください。

注意

スキルはクライアント間で自動同期されません。複数の環境で使う場合は、それぞれに導入します。

Claude Code: プラグインとして導入（推奨）​

マーケットプレイスの登録とプラグインのインストールは別の操作です。Claude Code 内で以下の 2 つのコマンドを実行します。

/plugin marketplace add diverta/kuroco-skills
/plugin install kuroco-skills@diverta-kuroco-skills

シェルから実行する場合は以下のコマンドを使用します（対話操作なし）。

claude plugin marketplace add diverta/kuroco-skills
claude plugin install kuroco-skills@diverta-kuroco-skills

インストール結果に Run /reload-plugins to activate. と表示された場合は /reload-plugins を実行してください。

プラグインのスキルは kuroco-skills: 名前空間で提供されます（例: /kuroco-skills:admin-mcp）。明示的に呼ばなくても、関連する依頼があればエージェントが自動的に選択します。

skills CLI で導入​

skills.sh の CLI は Claude Code / GitHub Copilot / Cursor / Cline など 18 以上のエージェントに対応し、1 コマンドで導入できます。

npx skills add diverta/kuroco-skills
ヒント

skills.sh でインストールすると、Kuroco Skills と一緒に find-skills メタスキルも自動的にインストールされます。 find-skills があることで、Claude Code が適切なスキルを選択して呼び出せるようになり、Kurocoに関する質問に対して、kuroco-skills を適切に使用します。

Claude Code: 手動配置​

リポジトリには .claude-plugin/plugin.json が含まれるため、スキルディレクトリに直接クローンすると、次回セッションから kuroco-skills@skills-dir として自動で読み込まれます（マーケットプレイスの登録もインストール操作も不要です）。

すべてのプロジェクトで利用する場合:

mkdir -p ~/.claude/skills
git clone https://github.com/diverta/kuroco-skills.git ~/.claude/skills/kuroco-skills

特定のプロジェクトでのみ利用する場合:

mkdir -p .claude/skills
git clone https://github.com/diverta/kuroco-skills.git .claude/skills/kuroco-skills

Codex: リポジトリスキルとして利用​

Codex はプロジェクト内の .agents/skills/ 配下からスキルを認識します。リポジトリの .agents/skills/kuroco-* は skills/ の共有スキルを指す相対シンボリックリンクになっているため、クローンしたリポジトリを Codex で開けば利用できます。

git clone https://github.com/diverta/kuroco-skills.git
cd kuroco-skills

Codex で明示的に呼ぶ場合は $kuroco-app-builder、$kuroco-admin-mcp のように $ を付けます。関連する依頼では暗黙に選択される場合もあります。Claude Code の /kuroco-skills:app-builder とは呼び出し表記が異なりますが、参照する SKILL.md は同じです。

claude.ai: zip をアップロード​

claude.ai では [設定] → [機能]（Settings → Features）からスキルを zip でアップロードします。ファイル作成・コード実行が有効な Pro / Max / Team / Enterprise プランで利用できます。アップロードしたカスタムスキルはユーザー単位で、組織全体への配布や集中管理はできません。

claude.ai は GitHub リポジトリを直接参照できないため、スキルごとに zip をアップロードします。Releases から使いたいスキルの zip を直接ダウンロードできます（SKILL.md が zip のルートに入っています）。全スキルをまとめて取得する場合は kuroco-skills-all.zip をダウンロードして展開すると、スキルごとの zip が全部入っています（アップロードは展開後の zip を 1 つずつ行います）。

Claude API / Agent SDK​

Skills API（/v1/skills）でアップロードし、コード実行ツールの container パラメータで skill_id を指定します。ベータヘッダー skills-2025-10-02 が必要です。アップロードしたスキルはワークスペース全体で共有されます。

同梱ドキュメント​

Kuroco Skills には、Kuroco 公式ドキュメントがカテゴリ単位の統合ファイルとしてパッケージに同梱されています。 インストール後すぐに AI エージェントがドキュメントを横断検索して、正確な回答を提供できます。

お知らせ・リリースノートは鮮度が重要なため同梱されていません。これらは公式サイトを参照してください。

ドキュメントを最新の状態に保つには、パッケージを更新してください（更新方法を参照）。

基本的な使い方​

Kuroco Skills をインストールすると、Claude Code で Kuroco に関する質問をした際に、関連するスキルが自動的に呼び出されます。 特別なコマンドや操作は必要ありません。

Kurocoに関する質問をする​

以下のように Claude Code に質問すると、関連するスキルが自動的に使用されます。

質問例使用されるスキル
「Kuroco の API でログインを実装したい」api-content
「Nuxt3 で Kuroco のコンテンツを表示したい」frontend-integration
「バッチ処理で Slack 通知を送りたい」server-processing
「Smarty のプラグインの使い方を知りたい」server-processing
「サイトを KurocoFront にデプロイしたい」frontend-integration
「Kuroco でアプリを丸ごと作りたい」app-builder
「まず動く画面（プロトタイプ）を見せて」app-builder
「管理画面からコンテンツを作成したい」admin-mcp
「Claude Desktop から Kuroco を操作したい」admin-mcp
「コンテンツ構造を設計したい」「カテゴリとタグのどちらを使うべきか」content-structure-design
「コンテンツ定義を新しく作りたい」content-structure-creation
「会員グループをどう分ければいいか」「あとから SSO を繋げられるようにしたい」auth-design
「外部 API と連携したい」「API キーをどこに置くべきか」external-integration-design
「Kuroco の利用料が増えた原因を調べたい」api-performance-review
「セキュリティ設定に問題がないか確認したい」security-audit
「サイトの仕様書を作って」「コンテンツ定義を ER 図にして」spec-writer
「Kuroco のドキュメントでエンドポイント設定を調べたい」kuroco-docs

Claude に Kuroco の管理操作をさせる（Admin MCP）​

Model Context Protocol にネイティブ対応するクライアント（Claude Code、Claude Desktop、Codex CLI など）向けに、Kuroco は Admin API を Admin MCP サーバとして直接公開しています。接続すれば、Claude Code に自然言語で指示するだけで管理操作を実行できます。

「ブログの記事を3件作成して」
「コンテンツ定義の一覧を確認したい」
「会員情報を取得してリストアップして」

エンドポイントは /direct/rcms_api/admin_mcp/ にマウントされ、HTTP POST + JSON-RPC 2.0 を受け付けます。ホストに応じて 2 種類の認証方式に対応します。

ホスト認証方式
管理画面 URL（ROOT_MNG_URL）管理セッション Cookie（管理画面ログインと同じ）
API URL（ROOT_API_URL）Authorization ヘッダの Bearer トークン

Bearer トークンは 2 種類を受け付けます。

  • OAuth Authorization Server アクセストークン: /direct/login/oauth_idp/{idpid}/token から target_domain=AdminMCP で発行。RFC 8707 / RFC 9728 に準拠した audience 拘束あり。エンドユーザー認可フロー向けの推奨方式です。
  • 特権 static トークン（api_id=-1）: 有効な管理セッションから AdminMCPServer::generateToken() で発行する Bearer。OAuth ハンドシェイクを張れないツール（プログラム的にトークンを取得して使うスクリプト、対話ログインを伴わない CI など）向けの経路です。

モジュールスコープ付き URL（/x/<csv>/readonly）の指定方法、認識される CSV エントリ、ツール名の規則などの詳細は MCP サーバ リファレンス を参照してください。

Claude Code への登録例​

# OAuth Authorization Server 認可（エンドユーザー向けの推奨）
claude mcp add --transport http kuroco-admin \
  https://example.g.kuroco.app/direct/rcms_api/admin_mcp/x/topics_group_1,member/readonly

# Static Bearer トークン（CI／無人エージェント向け）
claude mcp add --transport http kuroco-admin \
  https://example.g.kuroco.app/direct/rcms_api/admin_mcp/x/topics_group_1,member \
  --header "Authorization: Bearer <privileged-static-token>"

他クライアント別の設定方法や、ヘッダ受け渡しの詳細は MCP クライアント設定 を参照してください。

課金について

/direct/rcms_api/admin_mcp/ 配下のリクエストは /direct/ 経由として Kuroco の課金対象となります。AI エージェントが自律的に操作を繰り返すと意図せず多数のリクエストが発生する可能性があるため、読み取り中心のエージェントには /readonly、CSV のモジュール指定は本当に必要な範囲に絞ることを推奨します。

更新方法​

プラグインとして導入した場合は、マーケットプレイスとプラグインの両方を更新します。

/plugin marketplace update diverta-kuroco-skills
/plugin update kuroco-skills

更新の反映には Claude Code の再起動が必要です。

サードパーティのマーケットプレイスは、既定で自動更新が無効です。自動更新を有効にする場合は、/plugin → [Marketplaces] タブ → 対象のマーケットプレイスを選択 → [Enable auto-update] を選びます。

注記

/plugin marketplace add は登録のみを行うコマンドで、すでに登録済みのマーケットプレイスに対して実行しても最新版は取得されません（already on disk と表示されます）。更新には /plugin marketplace update を使用してください。

skills CLI で導入した場合は、同じコマンドを再実行します。

npx skills add diverta/kuroco-skills

手動配置した場合と、Codex でリポジトリスキルとして利用している場合は、git pull で更新します。

cd ~/.claude/skills/kuroco-skills
git pull origin main

claude.ai にアップロードした場合は、新しい zip をダウンロードしてアップロードし直します。

リポジトリ構成​

kuroco-skills/
├── .claude-plugin/
│   ├── marketplace.json         # マーケットプレイスカタログ
│   └── plugin.json              # プラグインメタデータ
├── .agents/skills/              # Codex がスキルを認識するための skills/ へのシンボリックリンク
├── skills/
│   ├── kuroco-docs/             # ドキュメント検索 + 公式ドキュメント（同梱）
│   ├── app-builder/             # アプリ・サイトの構築ワークフロー（フロントエンド先行）
│   ├── api-content/             # API パターン + コンテンツ CRUD
│   ├── frontend-integration/    # Vite/Nuxt/Next.js 統合 + 公開先の決定 + KurocoFront デプロイ
│   ├── server-processing/       # Smarty プラグインリファレンス + バッチ & Webhook
│   ├── admin-mcp/               # Admin MCP 接続、OAuth/CIMD、スコープ
│   ├── content-structure-design/    # コンテンツ構造の設計判断（作成の前段）
│   ├── content-structure-creation/  # MCP によるコンテンツ定義作成
│   ├── auth-design/             # 会員認証・権限の設計判断
│   ├── external-integration-design/ # 外部システム連携方式の設計判断
│   ├── security-audit/          # セキュリティ設定チェック
│   ├── api-performance-review/  # API パフォーマンス・コストレビュー
│   └── spec-writer/             # 実設定からの仕様書生成
├── scripts/
│   ├── consolidate_docs.py      # 同梱ドキュメントの統合ファイル再生成（メンテナ向け）
│   └── build-skill-zips.sh      # スキルごとの zip を dist/ に生成（リリース用）
├── tests/
│   └── skill-trigger/           # スキル選択（description）のリグレッションテスト
└── README.md

関連ドキュメント​

サポート

お探しのページは見つかりましたか？解決しない場合は、問い合わせフォームからお問い合わせいただくか、Slackコミュニティにご参加ください。

フォームから問い合わせをする
Slackコミュニティに参加する