Kuroco Skills for Claude Code の使い方

Kuroco Skills は、Claude Code 向けのスキルパッケージです。 Kuroco の API 連携、コンテンツ管理、フロントエンド統合、バッチ処理などに関するベストプラクティスを Claude Code に学習させ、Kuroco 開発の生産性を向上させます。

Kuroco AI アーキテクチャ

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

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

管理操作の AI 連携には 2 つの経路があります。

Kuroco Skills の kuroco-admin-api スキルは内部で Admin CLI を呼び出します。管理画面と同じログインセッションを使うため、ローカル開発に適しています。
Admin MCP サーバは MCP 対応クライアント（Claude Code、Claude Desktop など）に直接登録でき、Bearer トークンで認証します。無人エージェント、OAuth ベースの認可、スコープ／読み取り専用のアクセス制御に適しています。

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

Kuroco Skills とは

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

スキル	説明
kuroco-docs	Kuroco 公式ドキュメントの検索・参照
kuroco-api-content	API 設計・認証（Cookie/Token/StaticToken）、CORS、コンテンツ CRUD、フィルタークエリ
kuroco-frontend-integration	Nuxt.js / Next.js 統合、SSG/SSR、認証実装、AI 自動デプロイ
kuroco-server-processing	Smarty プラグイン・構文リファレンス（206 プラグイン）、バッチ処理、Webhook、トリガー
kuroco-admin-api	管理 API（admin_api）の CLI 経由操作（kuroco-admin CLI）

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

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

Kuroco Skills を使用するには Claude Code が必要です。

注意

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 セットアップガイドを参照してください。

インストール方法

方法 1: skills.sh からインストール（推奨）

skills.sh は AI エージェント向けスキルのオープンマーケットプレイスです。

npx skills add diverta/kuroco-skills

ヒント

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

方法 2: Claude Code コマンドで追加

Claude Code 内で以下のコマンドを実行します。

/plugin marketplace add diverta/kuroco-skills

方法 3: 手動でクローン（グローバル）

すべてのプロジェクトで Kuroco Skills を利用する場合は、グローバルにインストールします。

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

方法 4: プロジェクトローカルに追加

特定のプロジェクトでのみ利用する場合は、プロジェクトディレクトリに追加します。

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

同梱ドキュメント

Kuroco Skills には、Kuroco 公式ドキュメントがプラグインに同梱されています。インストール後すぐに Claude Code がドキュメントを横断検索して、正確な回答を提供できます。

ドキュメントを最新の状態に保つには、プラグイン自体を更新してください（更新方法を参照）。

基本的な使い方

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

Kurocoに関する質問をする

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

質問例	使用されるスキル
「Kuroco の API でログインを実装したい」	api-content
「Nuxt3 で Kuroco のコンテンツを表示したい」	frontend-integration
「バッチ処理で Slack 通知を送りたい」	server-processing
「Smarty のプラグインの使い方を知りたい」	server-processing
「サイトを自動デプロイしたい」	frontend-integration
「管理画面からコンテンツを作成したい」	admin-api
「Kuroco のドキュメントでエンドポイント設定を調べたい」	kuroco-docs

Claude に Kuroco の管理 API を操作させる

kuroco-admin-api スキルを使うと、Claude Code から kuroco-admin CLI 経由で Kuroco の管理 API（admin_api）を操作できます。 kuroco-admin login で保存されたセッション Cookie を利用するため、別途 API キーを設定する必要はありません。

課金について

admin_api へのリクエストは /direct/rcms_api/admin_api/ エンドポイントを通じて実行されます。 /direct/ 配下へのリクエストは Kuroco の 課金対象となります。 AI エージェントが自律的に操作を繰り返す場合、意図せず多数のリクエストが発生する可能性があるため、ご注意ください。

セットアップ手順

ステップ 1: Bun ランタイムをインストールする

CLI のビルドに必要な Bun をインストールします。

curl -fsSL https://bun.sh/install | bash

ステップ 2: kuroco-admin CLI をビルド・インストールする

cd /path/to/admin_cli
bun build --compile kuroco-admin.ts --outfile kuroco-admin
cp kuroco-admin /usr/local/bin/

action リネーム前のバイナリは再ビルドが必要

admin_api ゲートウェイのメタエンドポイントは MODE=... から action=... に変更されています。それ以前にビルドしたバイナリは旧エンドポイントを呼ぶため動作しません。すでに kuroco-admin をビルド済みの場合は、最新ソースを取得して再ビルドしてください。

cd /path/to/admin_cli
git pull
bun build --compile kuroco-admin.ts --outfile kuroco-admin
cp kuroco-admin /usr/local/bin/

ステップ 3: Kuroco 管理画面にログインする

kuroco-admin login --url https://example.g.kuroco-mng.app

メールアドレスとパスワードの入力を求められます。セッション Cookie は ~/.kuroco-admin/cookies.txt（mode 0o600）に保存されます。

非対話の認証

CI/CD や無人エージェントでは、login の代わりに以下の環境変数を設定します。環境変数は保存済みの認証情報より優先されます。

export KUROCO_ADMIN_URL="https://example.g.kuroco-mng.app"
export KUROCO_ADMIN_COOKIE="__Host-rcms_api_access_token=xxxxxxxx"

使い方

Claude Code に自然言語で指示するだけで、管理 API の操作を自動化できます。

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

仕組み

Claude は内部で以下の kuroco-admin CLI コマンドを使い分けて操作を実行します。

コマンド	役割
`kuroco-admin whoami`	セッション情報の確認（member_id、名前、権限）
`kuroco-admin discover`	利用可能なモジュール・コントローラの探索
`kuroco-admin advise`	AI 支援：やりたいことを伝えると API 手順を回答
`kuroco-admin help`	コントローラのリクエスト・レスポンススキーマ取得
`kuroco-admin exec`	API 実行（GET/POST）、`--columns` でレスポンス絞り込み可能

注意

変更操作（作成・更新・削除）を実行する前に、Claude は必ずユーザーに確認を求めます。意図しない操作が実行されることはありませんが、指示は具体的に記述することを推奨します。

MCP 対応クライアントから Admin MCP に接続する

Model Context Protocol にネイティブ対応するクライアント（Claude Code、Claude Desktop、Codex CLI など）向けに、Kuroco は Admin API を Admin MCP サーバとして直接公開しています。CLI のビルドは不要です。

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

認証失敗時の 401 レスポンスには RFC 6750 準拠の WWW-Authenticate チャレンジが含まれ、resource_metadata で次の公開エンドポイントを案内します。

/.well-known/oauth-protected-resource/direct/rcms_api/admin_mcp/

MCP クライアントは事前認証なしで Authorization Server を発見できます。

モジュールスコープ付き MCP サーバ

URL のパスセグメントで、1 つの MCP 接続に複数の管理モジュールをバンドルできます（GitHub MCP の /x/<csv>/readonly パターンに準拠）。

POST /direct/rcms_api/admin_mcp/                                     # 全ツール（管理／discovery のみ）
POST /direct/rcms_api/admin_mcp/x/topics_group_1,topics_group_5,member,services
POST /direct/rcms_api/admin_mcp/x/topics_group_1,topics_group_5/readonly

認識される CSV エントリ:

エントリ	意味
`topics_group_<N>`	`topics_group_id = N` にスコープした topics レコード操作。各ツールの `topics_group_id` 引数は enum として制約され、許可外グループへの呼び出しは拒否されます。
`topics`	グループ制約なしの同等表現。discovery 専用で、ツール呼び出しは拒否されます。
`topics_group`	グループ定義の管理（`t_topics_group` の CRUD）。
`services`	サービスモデル（Email、Slack など）。
`<mt>`	その他任意の管理モジュール（`member`、`ec`、`batch` など）。

パスに /readonly を付与すると、書き込み系ツール（INSERT / UPDATE / DELETE）はリストから除外されます。

ツール名の規則

ツール名はコントローラ名をそのまま使うのではなく、{mt}-{verb} の畳まれた形式で生成されます。動詞はコントローラ名の語尾と MODE から導出されます（例: INSERT → create）。

種別	パターン	例
List コントローラ（`{mt}_list_api`、MODE なし）	`{mt}-list`	`topics-list`
List コントローラ + MODE	`{mt}-{mode}`	`topics-accept`
List コントローラの一括処理 MODE（DELETE 等）	`{mt}-bulk_{mode}`	`topics-bulk_delete`
用途特化型の list（`{mt}_{spec}_list_api`）	`{mt}-{spec}_list`	`topics-waiting_for_approval_list`
Edit コントローラ INSERT	`{mt}-create`	`topics-create`
Edit コントローラ UPDATE	`{mt}-update`	`topics-update`
Edit コントローラ DELETE	`{mt}-delete`	`topics-delete`
Edit コントローラ VALIDATE	`{mt}-validate`	`topics-validate`
サブエンティティのコントローラ（`topics_group_edit_api` など）	`{mt}-{sub}-{verb}`	`topics-group-create`
Fetch ヘルパー	`{mt}-fetch`	`topics-fetch`
topics 専用の describe ツール（ハードコード）	—	`topics-describe`
サービスメソッド	`{mt}-{method}`	`Email-send`

実際のツール一覧は、スコープ URL に対して JSON-RPC の tools/list を発行して確認してください。モジュールが公開するコントローラに応じて名前は変化します。

Claude Code への登録例

# OAuth IdP 認可（エンドユーザー向けの推奨）
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 の課金対象となります（Admin CLI と同様）。読み取り中心のエージェントには /readonly、CSV のモジュール指定は本当に必要な範囲に絞ることを推奨します。

更新方法

Kuroco Skills を最新の状態に保つには、以下のいずれかの方法でアップデートします。

/plugin marketplace update kuroco-skills

または手動で更新します。

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

リポジトリ構成

kuroco-skills/
├── .claude-plugin/
│   └── plugin.json              # プラグインメタデータ
├── skills/
│   ├── kuroco-docs/             # ドキュメント検索 + 公式ドキュメント（同梱）
│   ├── api-content/             # API パターン + コンテンツ CRUD
│   ├── frontend-integration/    # Nuxt/Next.js 統合 + AI 自動デプロイ
│   ├── server-processing/       # Smarty プラグインリファレンス + バッチ & Webhook
│   └── admin-api/               # 管理 API CLI 操作
└── README.md

サポート

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

フォームから問い合わせをする

Slackコミュニティに参加する

Kuroco AI アーキテクチャ​

Kuroco Skills とは​

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

macOS の場合​

Windows の場合​

インストール方法​

方法 1: skills.sh からインストール（推奨）​

方法 2: Claude Code コマンドで追加​

方法 3: 手動でクローン（グローバル）​

方法 4: プロジェクトローカルに追加​

同梱ドキュメント​

基本的な使い方​

Kurocoに関する質問をする​

Claude に Kuroco の管理 API を操作させる​

セットアップ手順​

使い方​

仕組み​

MCP 対応クライアントから Admin MCP に接続する​

モジュールスコープ付き MCP サーバ​

ツール名の規則​

Claude Code への登録例​

更新方法​

リポジトリ構成​

関連ドキュメント​