confluent-tuning-advisor

Files (6)

• SKILL.md
• evals.json · evals/
• confluent-cloud.md · references/
• confluent-platform.md · references/
• monitoring.md · references/
• tuning-parameters.md · references/

SKILL.md (first lines)

# Confluent Tuning Advisor

Turns a workload's priority (latency, throughput, availability, or durability) into a concrete,
platform-appropriate **recommendation**: which Kafka settings to change, from what to what, why,
what it trades against, and how the administrator should validate it afterward. Targets
**Confluent Cloud** and **Confluent Platform** only. **Kafka only** — Flink (including Flink SQL
job tuning) is out of scope; see the "Do NOT trigger" clause in the description.

These four priorities are not independent — every recommendation trades against at least one
other axis. The core job of this skill is to make that trade-off explicit, not to pretend a
free lunch exists.

> **Advisory-only — this skill never changes anything.** It may inspect configuration and runtime
> state (read-only) and propose changes. It must **never** apply changes, run write/produce
> operations, or otherwise mutate a broker, topic, or client — the administrator or developer is
> solely responsible for reviewing and applying any recommendation. Keep recommendation and
> execution strictly separate: present the proposed change, do **not** ask for permission to apply
> it, do **not** apply it, and never state or imply that a change has been made. This skill ships no
> executable scripts; the only actions it takes are **read-only** config/metric inspection via the
> Confluent CLI, an MCP server, or the Kafka REST v3 / REST Proxy v3 and Cloud Metrics APIs.

## When to read which file

| Situation | Read this |
|---|---|
| User is targeting Confluent Cloud | [references/confluent-cloud.md](references/confluent-cloud.md) |
| User is targeting Confluent Platform (self-managed) | [references/confluent-platform.md](references/confluent-platform.md) |
| Any config knob lookup by priority (producer/consumer/topic/broker) | [references/tuning-parameters.md](references/tuning-parameters.md) |
| Verifying a **Platform** change, or choosing which broker JMX metric proves it worked (Step 7) | [references/monitoring.md](references/monitoring.md) |
| Verifying a **Cloud** change, or choosing which metric proves it worked (Step 7) | [references/confluent-cloud.md](references/confluent-cloud.md) for server-side metrics; use [references/monitoring.md](references/monitoring.md) only for the client-metrics sections |

Do not read all of these upfront — pull in only what the current step needs.

## Core workflow

1. Capture the workload and priority
2. Detect platform (Cloud vs Platform) and read the matching reference file
3. Inspect the current effective config as a baseline (read-only)
4. Look up recommendations in `references/tuning-parameters.md`
5. Present the recommendation — proposed changes with rationale, impact, risks, prerequisites, and
   validation steps (do not ask to apply, do not apply)
6. Hand off to the administrator, who reviews and applies it themselves
7. Give the administrator the validation steps to confirm the change once they apply it
8. Iterate on the recommendation if the target still isn't met

---

## Step 1: Capture the workload and priority

Ask, in one pass:

1. **Primary priority** — exactly one of: latency, throughput, availability, durability.
   A user may name a secondary priority too; make clear the primary always wins when they conflict.
2. **What "good" looks like, quantified** — e.g. "p99 producer-to-consumer latency under 20ms",
   "sustain 200 MB/s", "survive loss of one AZ with zero downtime", "zero data loss even if a
   broker dies mid-write". Vague goals ("make it fast") should be pushed back on — ask for a number.
3. **Workload shape** — approximate message size, expected messages/sec, number of
   producers/consumers, whether messages are transactional/exactly-once, current topic name(s)
   and partition count if they already exist.
4. **What's actually hurting today**, if this is an existing workload (a specific symptom beats a
   guess).

If the user only says which axis matters and nothing else, proceed with the interview above
before touching any reference file — the recommendation depends on the quantified target, not
just the axis name.

## Step 2: Detect platform

Ask which platform this workload runs on: **Confluent Cloud** or **Confluent Platform**
(self-managed). This skill does not cover WarpStream or unmanaged Apache Kafka — say so and stop
if the user names one of those. It also does not cover **Kafka Connect** (connector or worker
tuning) — if the request is about a connector or Connect worker, say it's out of scope and stop.

**Flink is a hard stop.** If the request mentions Flink at all — a Flink SQL job, a Flink pipeline,
parallelism, checkpointing, state backend, a lagging/slow Flink statement, a UDF — this skill does
not apply. Say it's out of scope and route the user to `confluent-cloud-flink-sql` (Flink SQL) or
`flink-udf` (Flink UDFs), then **stop**. Do **not** proceed into the workflow, and do **not** offer
to tune the underlying Kafka topic/producer/consumer as a fallback or consolation — declining is the
whole response. (If the user later comes back with a request that is solely about Kafka topic or
client configuration, with no Flink tuning ask, treat that as a fresh in-scope request.)

**Every out-of-scope handoff follows that same rule.** Whenever this skill declines — new client
application code (`developing-kafka-java-client`, `developing-kafka-python-client`), Kafka Streams
(`kafka-streams-programming`), Kafka Connect, CDC/Tableflow (`confluent-cloud-cdc-tableflow`),
WarpStream, or Apache Kafka OSS — name the right skill and stop. Do not attach tuning
recommendations, default values, or "worth deciding up front" configuration advice to the handoff.
Offering `acks`, partition-count, or any other setting alongside a decline is still a tuning
recommendation, and it is exactly what makes the handoff fail. Declining is the whole response.

Read the matching reference file now:
- Confluent Cloud → [references/confluent-cloud.md](references/confluent-cloud.md) — cluster
  tier limits, what Confluent manages vs. what you can set, quota mechanics.
- Confluent Platform → [references/confluent-platform.md](references/confluent-platform.md) —
  broker-level knobs, rack awareness, JVM/OS-level factors that matter for tail latency.

## Step 3: Inspect the current config as a baseline (read-only)

Before recommending anything, capture what's actually configured today — recommendations phrased
as diffs are easier to reason about and to confirm than absolute values. This is a **read-only**
inspection (a `describeConfigs`); it changes nothing. Use whichever of these the environment
already has:

- **CLI**: use the current Confluent CLI documentation to find the read-only topic-description
  operation for the target platform and installed CLI version.
- **MCP tools**: discover a read-only topic-description or topic-config listing tool from the
  configured Confluent MCP server — preferred for discovery when available.
- **REST**: use the read-only topic-config listing operation in the current
  [Confluent Cloud Kafka REST v3 API reference](https://docs.confluent.io/cloud/current/api.md#tag/Cluster-(v3))
  or [Confluent Platform REST Proxy v3 API reference](https://docs.confluent.io/platform/current/kafka-rest/api.md#rest-proxy-v3),
  as appropriate. A Kafka bootstrap address is not an HTTP endpoint; use the cluster's advertised
  REST endpoint.

For a planned topic that does not exist, do not attempt to describe it. Record its topic config as
"not created", then inspect only the cluster defaults and capacity limits needed to size it. In
Step 5, present proposed initial values rather than a current → recommended diff for that topic.

For broker/cluster-level baselines (Platform only — Cloud does not expose these), use the CLI/REST
equivalent of `describeConfigs` against the **broker** resource. Capture the values you'll be
proposing to change, so Step 5 can be written as a clean current → recommended diff.

From confluentinc/agent-skills, Apache-2.0.

More from confluentinc/agent-skills