How to use Kuroco Skills for Claude Code

Kuroco Skills is a skill package for Claude Code. It teaches Claude Code best practices for Kuroco API integration, content management, frontend integration, and batch processing, improving productivity in Kuroco development.

Kuroco AI Architecture

Kuroco provides the following interfaces for AI integration:

Component	Type	Description
Admin Panel	Web UI	Kuroco management screen for administrators
Admin API	REST API	Management operations via API (`/direct/rcms_api/admin_api/`)
Admin CLI	CLI Tool	CLI wrapper for Admin API (`kuroco-admin`)
Admin MCP	MCP Server	MCP Server for Admin API (`/direct/rcms_api/admin_mcp/`), Bearer token authentication
Client API	REST API	Public-facing API for frontend apps (`/rcms-api/{id}/`)
Client API	MCP Server	MCP Server for Client API (`/rcms-api/{id}/mcp`)
Client CLI	CLI Tool	CLI wrapper for Client API (`kuroco-client`)

For admin operations, Kuroco offers two AI integration paths:

The kuroco-admin-api skill in Kuroco Skills uses the Admin CLI under the hood — best for local development with the same login session as the admin UI.
The Admin MCP Server can be registered directly with MCP-aware clients (Claude Code, Claude Desktop, etc.) and is authenticated via Bearer token — best for unattended agents, OAuth-based authorization, and scoped/read-only access.

Client CLI is a standalone command-line tool that can be used independently.

What is Kuroco Skills

Once installed, Claude Code can provide accurate, concrete code examples and best practices when answering questions about Kuroco. The package includes the following 5 skills:

Skill	Description
kuroco-docs	Search and reference Kuroco official documentation
kuroco-api-content	API design, authentication (Cookie/Token/StaticToken), CORS, content CRUD, filter queries
kuroco-frontend-integration	Nuxt.js/Next.js integration, SSG/SSR, authentication, AI automated deployment
kuroco-server-processing	Smarty plugin & syntax reference (206 plugins), batch processing, webhooks, triggers
kuroco-admin-api	Management API (admin_api) CLI operations (kuroco-admin CLI)

For details on each skill, see the Kuroco Skills Reference.

Prerequisites: Install Claude Code

Kuroco Skills requires Claude Code to be installed.

caution

Claude Code has been tested with the desktop (CLI) version only. Operation on the web version (claude.ai) has not been verified.

macOS

Use the native installer (recommended) or Homebrew:

# Native installer (recommended, auto-updates)
curl -fsSL https://claude.ai/install.sh | bash

# Or via Homebrew
brew install --cask claude-code

After installation, run claude in your terminal to start Claude Code.

Windows

Use the native installer (recommended), WinGet, or WSL:

# PowerShell (recommended, auto-updates)
irm https://claude.ai/install.ps1 | iex

# Or via WinGet
winget install Anthropic.ClaudeCode

After installation, run claude in your terminal (PowerShell or Command Prompt) to start Claude Code.

note

On Windows, both native (requires Git Bash) and WSL are supported. WSL 2 is recommended for the best experience. For details, see the Claude Code official documentation.

For more installation options, see the Claude Code setup guide.

Installation

Method 1: Install from skills.sh (Recommended)

skills.sh is an open marketplace for AI agent skills.

npx skills add diverta/kuroco-skills

Why skills.sh is recommended

When installed using skills.sh, the find-skills meta-skill is automatically installed along with Kuroco Skills.

By having find-skills available, Claude Code can select and invoke the appropriate skills, and it will properly use kuroco-skills in response to questions about Kuroco.

Method 2: Add via Claude Code command

Run the following command in Claude Code:

/plugin marketplace add diverta/kuroco-skills

Method 3: Manual clone (Global)

To use Kuroco Skills across all projects, install globally:

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

Method 4: Add to project locally

To use only in a specific project, add to the project directory:

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

Bundled documentation

Kuroco Skills comes with official Kuroco documentation bundled in the plugin. After installation, Claude Code can immediately search across the documentation for accurate answers.

To keep the documentation up to date, update the plugin itself (see Updating).

Basic usage

Once Kuroco Skills is installed, relevant skills are automatically invoked when you ask Claude Code questions about Kuroco. No special commands or operations are required.

Ask a question about Kuroco.

Ask Claude Code questions like these, and the relevant skill will be used automatically:

Question	Skill used
"I want to implement login with Kuroco API"	api-content
"I want to display Kuroco content with Nuxt3"	frontend-integration
"I want to send Slack notifications from batch processing"	server-processing
"I want to know how to use Smarty plugins"	server-processing
"I want to auto-deploy a site"	frontend-integration
"I want to create content from the admin panel"	admin-api
"I want to search endpoint settings in Kuroco docs"	kuroco-docs

Letting Claude Operate Kuroco via Admin API

By using the kuroco-admin-api skill, Claude Code can operate Kuroco’s Management API (admin_api) via the kuroco-admin CLI. Authentication uses session cookies saved by kuroco-admin login, so no additional API key configuration is needed.

Billing notice

admin_api requests are executed through the /direct/rcms_api/admin_api/ endpoint. Requests under /direct/ are billable in Kuroco. Be aware that when an AI agent operates autonomously and repeatedly, a large number of requests may be generated unintentionally.

Setup Steps

Step 1: Install Bun runtime

Install Bun, which is required to build the CLI:

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

Step 2: Build and install kuroco-admin CLI

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

Rebuild required if the binary predates the action dispatch rename

The admin_api gateway switched meta-endpoint dispatch from MODE=... to action=.... Binaries built before that change call the old endpoints and will fail. If you already have a kuroco-admin binary, pull the latest source and rebuild:

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

Step 3: Log in to the Kuroco admin panel

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

You will be prompted for your email and password. Session cookies are saved to ~/.kuroco-admin/cookies.txt (mode 0o600).

Non-interactive authentication

For CI/CD or unattended agents, set the following environment variables instead of running login. Env vars take precedence over saved credentials.

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

Usage

Simply give instructions to Claude Code in natural language to automate admin API operations.

"Create three blog posts."
"I want to check the list of content definitions."
"Retrieve member information via the API and list it."
"Add a category via the management API."

How It Works

Claude internally uses the following kuroco-admin CLI commands to perform operations:

Command	Role
`kuroco-admin whoami`	Check session information (member_id, name, permissions)
`kuroco-admin discover`	Explore available modules and controllers
`kuroco-admin advise`	AI-powered: describe what you want, get API steps
`kuroco-admin help`	Get request/response schemas for a controller
`kuroco-admin exec`	Execute API (GET/POST) with optional `--columns` filtering

caution

Before executing any modification operations (create, update, delete), Claude will always ask the user for confirmation.
Unintended actions will not be executed, but it is recommended to provide clear and specific instructions.

Connecting MCP-aware clients to Admin MCP

For clients that natively speak the Model Context Protocol (Claude Code, Claude Desktop, Codex CLI, etc.), Kuroco also exposes the Admin API as an Admin MCP Server. No CLI build is required.

The endpoint is mounted at /direct/rcms_api/admin_mcp/ and accepts JSON-RPC 2.0 over HTTP POST. It supports two authentication modes depending on the host:

Host	Authentication
Management URL (`ROOT_MNG_URL`)	Admin session cookie (same as the admin UI login)
API URL (`ROOT_API_URL`)	Bearer token in `Authorization` header

For Bearer authentication, two token shapes are accepted:

OAuth IdP access token issued by /direct/login/oauth_idp/{idpid}/token with target_domain=AdminMCP. Audience-bound per RFC 8707 / RFC 9728 — recommended for end-user authorization flows.
Privileged static token (api_id=-1): a Bearer obtained from an active management session via AdminMCPServer::generateToken(). Use this for tools that cannot perform an OAuth handshake — programmatic issuance, scripted agents, CI without an interactive login.

401 responses include an RFC 6750 WWW-Authenticate challenge with resource_metadata pointing to:

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

so MCP clients can discover the Authorization Server without prior credentials.

Module-scoped MCP servers

You can bundle one or more admin modules into a single MCP connection by appending a path segment (modeled after the GitHub MCP /x/<csv>/readonly pattern):

POST /direct/rcms_api/admin_mcp/                                     # All tools (admin/discovery only)
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

Recognized CSV entries:

Entry	Meaning
`topics_group_<N>`	Topics record controllers scoped to `topics_group_id = N`. The `topics_group_id` argument is exposed as an enum in each tool, and calls outside the allowed list are rejected.
`topics`	Same as above with no group restriction. Discovery only — tool calls are rejected.
`topics_group`	Group definition management (CRUD on `t_topics_group`).
`services`	Service models (Email, Slack, etc.).
`<mt>`	Any other admin module (`member`, `ec`, `batch`, etc.).

Appending /readonly to the path removes write tools (INSERT / UPDATE / DELETE) from the listing.

Tool naming

Tool names use a folded {mt}-{verb} form rather than the raw controller name. The verb is derived from the controller suffix and MODE (e.g. INSERT → create):

Surface	Tool name pattern	Example
List controller (`{mt}_list_api`), no MODE	`{mt}-list`	`topics-list`
List controller with MODE	`{mt}-{mode}`	`topics-accept`
List controller, bulk MODE (DELETE etc.)	`{mt}-bulk_{mode}`	`topics-bulk_delete`
Specialized list (`{mt}_{spec}_list_api`)	`{mt}-{spec}_list`	`topics-waiting_for_approval_list`
Edit controller, INSERT	`{mt}-create`	`topics-create`
Edit controller, UPDATE	`{mt}-update`	`topics-update`
Edit controller, DELETE	`{mt}-delete`	`topics-delete`
Edit controller, VALIDATE	`{mt}-validate`	`topics-validate`
Sub-entity controller (e.g. `topics_group_edit_api`)	`{mt}-{sub}-{verb}`	`topics-group-create`
Fetch helper	`{mt}-fetch`	`topics-fetch`
Topics-only describe tool	hardcoded	`topics-describe`
Service method	`{mt}-{method}`	`Email-send`

Verify the exact tool list for your install by issuing a JSON-RPC tools/list against the scoped URL — names depend on which controllers your modules expose.

Registering with Claude Code

# OAuth IdP-based authorization (recommended for end-user flows)
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 token (CI / unattended agents)
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>"

For more clients and header-passing rules, see MCP Client Configuration.

Same billing rule applies

Requests under /direct/rcms_api/admin_mcp/ are routed through /direct/ and are billable in Kuroco, just like Admin CLI requests. Prefer /readonly scoping for read-heavy agents and limit the module CSV to what each agent actually needs.

Updating

To keep Kuroco Skills up to date, use one of the following methods:

/plugin marketplace update kuroco-skills

Or update manually:

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

Repository structure

kuroco-skills/
├── .claude-plugin/
│   └── plugin.json              # Plugin metadata
├── skills/
│   ├── kuroco-docs/             # Documentation search + official docs (bundled)
│   ├── api-content/             # API patterns + Content CRUD
│   ├── frontend-integration/    # Nuxt/Next.js integration + AI deployment
│   ├── server-processing/       # Smarty plugin reference + Batch & webhook
│   └── admin-api/               # Management API CLI operations
└── README.md

Kuroco Skills Reference - Detailed description of each skill
Kuroco Skills GitHub Repository
Claude Code Official Documentation

Support

If you have any other questions, please contact us or check out Our Slack Community.

Contact form

Join Kuroco Slack community

Kuroco AI Architecture​

What is Kuroco Skills​

Prerequisites: Install Claude Code​

macOS​

Windows​

Installation​

Method 1: Install from skills.sh (Recommended)​

Method 2: Add via Claude Code command​

Method 3: Manual clone (Global)​

Method 4: Add to project locally​

Bundled documentation​

Basic usage​

Ask a question about Kuroco.​

Letting Claude Operate Kuroco via Admin API​

Setup Steps​

Usage​

How It Works​

Connecting MCP-aware clients to Admin MCP​

Module-scoped MCP servers​

Tool naming​

Registering with Claude Code​

Updating​

Repository structure​

Related documentation​