How to use Kuroco Skills
Kuroco Skills is an Agent Skills package for Kuroco development. It gives AI agents best practices for Kuroco API integration, content management, frontend integration, and batch processing, improving productivity in Kuroco development.
Agent Skills is a filesystem-based standard built around SKILL.md, supported by Claude Code and many other AI agents. Agents load only each skill's name and description at startup and read the body when a request matches (progressive disclosure), so installing skills costs almost no context until they are used.
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 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 from an AI agent, use Admin MCP. It can be registered directly with MCP-aware clients (Claude Code, Claude Desktop, etc.) and supports scoped and read-only access control via OAuth.
Client CLI is a standalone command-line tool that can be used independently.
What is Kuroco Skills
Once installed, AI agents can provide accurate, concrete code examples and best practices when answering questions about Kuroco. The package includes the following 13 skills:
| Skill | Description |
|---|---|
| kuroco-docs | Search and reference Kuroco official documentation |
| kuroco-app-builder | Workflow for building an app or site from scratch (mock-first → content structures → API → live data → deployment) |
| kuroco-api-content | API design, authentication (Cookie / dynamic and static access tokens), CORS, content CRUD, filter queries |
| kuroco-frontend-integration | Vite / Nuxt.js / Next.js integration, SPA/SSG/SSR, authentication, deployment to KurocoFront |
| kuroco-server-processing | Smarty plugin & syntax reference (205 plugins), batch processing, webhooks, triggers |
| kuroco-admin-mcp | Admin MCP (management MCP server) connection setup, OAuth / CIMD authentication, scopes, tool usage |
| kuroco-content-structure-design | Content structure design decisions (splitting content structures, compressing fields with JSON fields, representing master data, choosing a classification mechanism, ext_slug naming) |
| kuroco-content-structure-creation | Content Structure (TopicsGroup) creation via MCP tool, field type reference |
| kuroco-auth-design | Member authentication & permission design decisions (member groups, registration flows, access restriction scopes, password policies, enterprise SSO / SCIM integration) |
| kuroco-external-integration-design | External system integration design decisions (direct calls / proxy / ingestion, secret and token management) |
| kuroco-api-performance-review | API performance & usage-cost investigation (API analytics, cache configuration review, improvement proposals) |
| kuroco-security-audit | Read-only security configuration audit (API security, CORS, IP restrictions, permissions, tokens) |
| kuroco-spec-writer | Read-only specification generation from live settings, output as Markdown + Mermaid (field tables, ER diagrams, API lists) |
For details on each skill, see the Kuroco Skills Reference.
Prerequisites: Install Claude Code
To use Kuroco Skills with Claude Code, install Claude Code first. This step is not required when using Codex or claude.ai.
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.
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
Pick the method for the client you use.
Skills do not sync across clients. Install them separately in each environment where you want them.
Claude Code: install as a plugin (recommended)
Registering the marketplace and installing the plugin are separate steps. Run the following two commands in Claude Code:
/plugin marketplace add diverta/kuroco-skills
/plugin install kuroco-skills@diverta-kuroco-skills
To run them from a shell instead (no interactive steps):
claude plugin marketplace add diverta/kuroco-skills
claude plugin install kuroco-skills@diverta-kuroco-skills
If the installation result shows Run /reload-plugins to activate., run /reload-plugins.
Plugin skills are provided under the kuroco-skills: namespace (for example, /kuroco-skills:admin-mcp). You do not need to invoke them explicitly — the agent selects them automatically for related requests.
Install with the skills CLI
The skills.sh CLI supports more than 18 agents, including Claude Code, GitHub Copilot, Cursor, and Cline, and installs the skills with a single command.
npx skills add diverta/kuroco-skills
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.
Claude Code: manual placement
The repository includes .claude-plugin/plugin.json, so cloning it directly into a skills directory makes it load automatically as kuroco-skills@skills-dir from the next session (no marketplace registration or install step required).
To use it across all projects:
mkdir -p ~/.claude/skills
git clone https://github.com/diverta/kuroco-skills.git ~/.claude/skills/kuroco-skills
To use it only in a specific project:
mkdir -p .claude/skills
git clone https://github.com/diverta/kuroco-skills.git .claude/skills/kuroco-skills
Codex: use as repository skills
Codex discovers project skills under .agents/skills/. In this repository, .agents/skills/kuroco-* are relative symlinks to the shared skills under skills/, so opening the cloned repository in Codex is enough to use them.
git clone https://github.com/diverta/kuroco-skills.git
cd kuroco-skills
To invoke a skill explicitly in Codex, prefix it with $, as in $kuroco-app-builder or $kuroco-admin-mcp. It may also be selected implicitly for related requests. The invocation syntax differs from Claude Code's /kuroco-skills:app-builder, but both read the same SKILL.md files.
claude.ai: upload a zip
On claude.ai, upload skills as zip files from Settings → Features. This is available on Pro / Max / Team / Enterprise plans with file creation and code execution enabled. Uploaded custom skills are per-user; they cannot be distributed or managed centrally for a whole organization.
claude.ai cannot reference a GitHub repository directly, so each skill is uploaded as its own zip. You can download the zip for the skills you need from Releases (SKILL.md sits at the root of each zip). To get all of them at once, download kuroco-skills-all.zip and extract it — it contains every per-skill zip (upload the extracted zips one at a time).
Claude API / Agent SDK
Upload through the Skills API (/v1/skills), then reference the skill_id in the container parameter of the code execution tool. The skills-2025-10-02 beta header is required. Uploaded skills are shared workspace-wide.
Bundled documentation
Kuroco Skills comes with official Kuroco documentation bundled in the package as consolidated files per category. After installation, AI agents can immediately search across the documentation for accurate answers.
Announcements and release notes are not bundled because freshness matters for them. Refer to the official site for these.
To keep the documentation up to date, update the package (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 deploy a site to KurocoFront" | frontend-integration |
| "I want to build a whole app on Kuroco" | app-builder |
| "Show me a working screen (prototype) first" | app-builder |
| "I want to create content from the admin panel" | admin-mcp |
| "I want to operate Kuroco from Claude Desktop" | admin-mcp |
| "I want to design a content structure", "Should I use categories or tags?" | content-structure-design |
| "I want to create a new content definition" | content-structure-creation |
| "How should I split up member groups?", "I want to be able to add SSO later" | auth-design |
| "I want to integrate with an external API", "Where should I put the API key?" | external-integration-design |
| "Why did my Kuroco usage cost increase?" | api-performance-review |
| "I want to check whether my security settings are safe" | security-audit |
| "Write a specification document for my site", "Turn my content definitions into an ER diagram" | spec-writer |
| "I want to search endpoint settings in Kuroco docs" | kuroco-docs |
Letting Claude operate Kuroco via Admin MCP
For clients that natively speak the Model Context Protocol (Claude Code, Claude Desktop, Codex CLI, etc.), Kuroco exposes the Admin API as an Admin MCP Server. Once connected, you can drive admin operations by giving Claude Code instructions in natural language.
"Create three blog posts."
"I want to check the list of content definitions."
"Retrieve member information and list it."
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 Authorization Server access token issued by
/direct/login/oauth_idp/{idpid}/tokenwithtarget_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 viaAdminMCPServer::generateToken(). Use this for tools that cannot perform an OAuth handshake — programmatic issuance, scripted agents, CI without an interactive login.
For details on module-scoped URLs (/x/<csv>/readonly), recognized CSV entries, and tool naming rules, see the MCP Server Reference.
Registering with Claude Code
# OAuth Authorization Server-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.
Requests under /direct/rcms_api/admin_mcp/ are routed through /direct/ and are billable in Kuroco. An AI agent operating autonomously and repeatedly may generate a large number of requests unintentionally, so prefer /readonly scoping for read-heavy agents and limit the module CSV to what each agent actually needs.
Updating
If you installed the plugin, update both the marketplace and the plugin:
/plugin marketplace update diverta-kuroco-skills
/plugin update kuroco-skills
Restart Claude Code to apply the update.
Third-party marketplaces have auto-update disabled by default. To enable it, run /plugin → the Marketplaces tab → select the marketplace → Enable auto-update.
/plugin marketplace add only registers a marketplace — running it again on an already-registered one does not fetch the latest version (it reports already on disk). Use /plugin marketplace update to update.
If you installed with the skills CLI, rerun the same command:
npx skills add diverta/kuroco-skills
If you placed the repository manually, or use it as repository skills in Codex, update with git pull:
cd ~/.claude/skills/kuroco-skills
git pull origin main
If you uploaded zips to claude.ai, download the new zip and upload it again.
Repository structure
kuroco-skills/
├── .claude-plugin/
│ ├── marketplace.json # Marketplace catalog
│ └── plugin.json # Plugin metadata
├── .agents/skills/ # Symlinks to skills/ so Codex can discover them
├── skills/
│ ├── kuroco-docs/ # Documentation search + official docs (bundled)
│ ├── app-builder/ # App/site building workflow (frontend-first)
│ ├── api-content/ # API patterns + Content CRUD
│ ├── frontend-integration/ # Vite/Nuxt/Next.js integration + hosting choice + KurocoFront deployment
│ ├── server-processing/ # Smarty plugin reference + Batch & webhook
│ ├── admin-mcp/ # Admin MCP connection, OAuth/CIMD, scopes
│ ├── content-structure-design/ # Content structure design decisions (before creation)
│ ├── content-structure-creation/ # Content Structure creation via MCP
│ ├── auth-design/ # Member auth & permission design decisions
│ ├── external-integration-design/ # External system integration design decisions
│ ├── security-audit/ # Security configuration audit
│ ├── api-performance-review/ # API performance & cost review
│ └── spec-writer/ # Specification generation from live settings
├── scripts/
│ ├── consolidate_docs.py # Regenerates the bundled consolidated docs (for maintainers)
│ └── build-skill-zips.sh # Builds per-skill zips into dist/ (for releases)
├── tests/
│ └── skill-trigger/ # Skill selection (description) regression tests
└── README.md
Related documentation
- 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.