> ## Documentation Index
> Fetch the complete documentation index at: https://docs.risingwave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Choose and install RisingWave agent skills

> Choose between free public skills, embedded CLI skills, and paid Cloud diagnostic skills, then install the skills for your AI assistant.

RisingWave provides free skills for general development and CLI guidance, plus a paid Cloud package for cluster diagnostics. Choose the skills that match your workflow; the paid package is not required to use the free skills.

## Choose your skills

| Option | Use it for | Installation requirements |
| - | - | - |
| [Free public skills](#free-public-skills) | RisingWave development guidance and streaming SQL best practices. | Node.js and npm (`npx`); no Cloud login or paid package access required to install. |
| [Free CLI skills](#free-cli-skills) | Guidance for using `rwc` commands. | An installed `rwc` binary; no Cloud login or paid package access required to install. |
| [Paid Cloud skills](#paid-cloud-skills) | Discovering Cloud clusters and investigating metrics, logs, SQL, and operational symptoms. | An authenticated `rwc` CLI and an organization with access to the paid package. |

Installing any skill does not grant access to Cloud resources. Cloud operations still require valid credentials and the appropriate permissions.

## Free public skills

The public [RisingWave agent skills repository](https://github.com/risingwavelabs/agent-skills) includes:

* `risingwave`: guidance for connections, sources, materialized views, sinks, and streaming SQL.
* `risingwave-best-practices`: guidance for schema design, streaming queries, CDC, and performance.

With Node.js and npm installed, run the following from your project directory and select your assistant when prompted:

```bash theme={null}
npx skills add risingwavelabs/agent-skills
```

To select just one skill:

```bash theme={null}
npx skills add risingwavelabs/agent-skills --skill risingwave-best-practices
```

These skills do not install the paid Cloud diagnostic package.

## Free CLI skills

The [RisingWave Cloud CLI](https://docs.risingwave.com/cloud/install-cli.md) bundles command-reference skills with the binary. Installing them does not contact the paid package service or require CLI authentication.

Choose a supported target and run its command from your project directory:

```bash theme={null}
# Codex
rwc skill install --target codex

# Claude Code
rwc skill install --target claude-code

# Cursor
rwc skill install --target cursor
```

These embedded skills describe CLI commands; they are different from the paid diagnostic package installed with `--pro`. Authenticate the CLI separately before using it to operate on Cloud resources.

## Paid Cloud skills

The paid package provides instructions and tools for discovering clusters and investigating metrics, logs, and SQL performance through Cloud APIs.

> [!NOTE]
>
> The paid package requires an organization with access to paid agent skills. Check **AI Agent → Agent Skills** in the Cloud console for availability. Installing skills does not grant additional permissions: API requests use the permissions of the user or service account configured in your CLI.

### What's included

| Skill | Purpose |
| - | - |
| `rwc-cloud-discovery` | Discover account, region, and cluster context from your authenticated CLI. |
| `risingwave-cloud-metrics` | Investigate cluster health and performance using metrics. |
| `risingwave-cloud-logs` | Investigate errors and connector failures using cluster logs. |
| `risingwave-sql-diagnostics` | Inspect SQL execution plans, system catalogs, and diagnostic queries. |
| `risingwave-troubleshooting-runbooks` | Coordinate diagnostics for stalled streaming, source and sink failures, memory issues, and slow queries. |

### Step 1: Prepare your CLI

[Install the latest RisingWave Cloud CLI](https://docs.risingwave.com/cloud/install-cli.md) and check its version:

```bash theme={null}
rwc version
```

The diagnostic helper also requires Node.js 20 or later. Use a CLI release that supports `--pro` and includes the paid package verification key. If installation reports `paid skill release trust root is not configured`, update the CLI; do not disable signature verification.

### Step 2: Authenticate

Browser sign-in does not authenticate the CLI. Choose either method below.

> [tab] Service account API key
>
> Service accounts work with CLI, agent, and automation workflows, regardless of how you sign in to the console.
>
> 1. Open **AI Agent → Credentials** in the Cloud console.
> 2. Create a service account, or select one you have permission to use. Creating service accounts and keys requires the appropriate organization permissions.
> 3. Create an API key and save its secret, which is shown only once.
> 4. Configure the CLI with that key:
>
> ```bash theme={null}
> rwc auth config --api-key '<key>' --api-key-secret '<secret>'
> ```
>
> Use a service account in the organization that has access to the package. Access to cluster metrics, logs, and SQL also depends on that service account's permissions. See [Role-based access control](https://docs.risingwave.com/cloud/organization-rbac.md).

> [tab] Email and password
>
> If your account has a RisingWave Cloud password, sign in using the interactive password prompt:
>
> ```bash theme={null}
> rwc auth login --account 'you@example.com'
> ```
>
> Do not enter a Google or other identity-provider password. You can use a service account API key instead.

> [!WARNING]
>
> Keep API secrets and CLI configuration private. Do not paste them into assistant conversations, logs, or source control. Your shell may save commands containing secrets in its history; use your organization's approved credential-handling practices.

### Step 3: Install for your assistant

In **AI Agent → Agent Skills**, the **Paid Agent Skills** panel shows the available package version and installation commands.

For a project-local installation, run the command from the project directory where you use your assistant. Choose your target:

> [tab] Codex
>
> ```bash theme={null}
> rwc skill install --pro --target codex
> ```
>
> Installs under `.agents/skills/` in the current project.

> [tab] Claude Code
>
> ```bash theme={null}
> rwc skill install --pro --target claude-code
> ```
>
> Installs under `.claude/skills/` in the current project.

> [tab] Cursor
>
> ```bash theme={null}
> rwc skill install --pro --target cursor
> ```
>
> Installs under `.agents/skills/` in the current project.

> [tab] GitHub Copilot
>
> ```bash theme={null}
> rwc skill install --pro --target copilot
> ```
>
> Installs under `.agents/skills/` in the current project.

> [tab] Claude Desktop
>
> ```bash theme={null}
> rwc skill install --pro --target claude-desktop
> ```
>
> Installs at user scope under `~/.claude/skills/`, not in the current project. This command writes the skill files; consult your client's skill-loading requirements to make them available in the assistant.

The installer checks your package access, downloads the package, verifies its signature and file hashes, and writes the installed files and a lockfile. Keep the lockfile with the installation.

### Step 4: Verify and use the skills

Verify the installed files with the same target and directory used for installation. For example, for Codex:

```bash theme={null}
rwc skill verify --target codex
rwc skill doctor --target codex
```

`verify` checks installed files against the lockfile. `doctor` checks the installed package and authenticated access to the package service; it is not a cluster health check.

Open the project in your assistant and follow that client's instructions for loading skills. Start with a bounded, read-only request, for example:

> Use the RisingWave Cloud skills to investigate streaming latency for my cluster over the last 30 minutes. Start by discovering the cluster and region, and report your findings without changing resources.

The discovery skill resolves the cluster's region; you do not need to select a region just to install the package. For manual CLI commands such as `rwc cluster list`, first [select a region](https://docs.risingwave.com/cloud/install-cli.md#step-3-select-a-region).

### Update the paid package

Run the installation command again to fetch the current package, using the same target and project directory:

```bash theme={null}
rwc skill install --pro --target codex
rwc skill verify --target codex
```

Keep your own notes or custom skills separate from the managed package files. If verification fails, do not edit the lockfile to suppress the mismatch; review local modifications before reinstalling.

## Related topics

* [Install the RisingWave Cloud CLI](https://docs.risingwave.com/cloud/install-cli.md)
* [Service accounts and API keys](https://docs.risingwave.com/cloud/service-account.md)
* [Role-based access control](https://docs.risingwave.com/cloud/organization-rbac.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.