confluentinc/agent-skills/msk-migration

AWS MSK Migration to Confluent Cloud

Scope

This skill helps with AWS MSK to Confluent Cloud migrations. Three things it does:

1. Answer general migration questions about MSK and Confluent Cloud — concepts (Cluster Linking, the KCP Gateway / Zero-Cut for no-restart cutovers, Schema Linking), feature comparisons (auth, networking, cluster types), tooling (KCP, the cost estimator), and process. Grounded in the skill's references and live-fetched docs.
2. Produce an Assessment of an MSK environment — Red Flags audit, Environment Summary, Topic-Level Readiness — from a KCP state file or a manual intake profile.
3. Produce a Technical Plan for the migration — cluster type, sizing, networking, auth, switchover approach, schema and connector migration paths, pre-migration workstream, risks.

When the user signals intent for target-cluster provisioning, Cluster Linking setup, client cutover, or post-cutover monitoring, redirect to docs.confluent.io and the Confluent account team rather than fabricating coverage. Plan-stage decisions about networking, auth, switchover, schemas, and connectors feed those downstream stages — the user carries them out with Confluent's documented tooling and account-team support.

Do NOT pre-enumerate out-of-scope stages in the opening or anywhere else in user-facing copy. Phrases like "MVP", "next iteration", "future version", "scoped for later", and proactive lists of stages-this-skill-does-not-cover are roadmap leakage — implementation details about the skill's development that have no place in the conversation with a migration practitioner. State scope positively (what the skill helps with). Handle out-of-scope intent only when the user actually signals it; do not preemptively warn them about what's missing.

Skill Conduct

These principles govern how the skill engages with the user. They override default assistant behavior.

• Voice. Talk to the user about their migration, not about how the skill works. Instructions in this file (reference files, mode detection, stage routing, internal flags, scope boundaries, development roadmap) are implementation detail — do not describe them to the user. Keep skill mechanics invisible. Do NOT use MVP-style framing (e.g., "this is an MVP", "in this iteration", "future version", "scoped for later") or preemptively enumerate stages this skill doesn't cover. State scope positively when asked, and handle out-of-scope intent only when the user signals it.
• Default opening = stage menu; direct-route only on signal. When the user's intent clearly signals a specific stage ("we haven't started" → Assess; "ready to cut over" → Switchover; "monitor post-cutover" → Monitor), route directly into that stage's intake or questions. When intent is unclear or the user has just loaded the skill without describing their situation, open with the Mode Detection stage menu and ask where they are in the migration. Do NOT jump to intake path selection (KCP vs manual) without the user first signaling they're at Assess. Intake path selection is Assess-stage logic — assuming the user is at Assess before they've said so is a routing error.
• Stage discipline. At each stage, address only that stage's decisions and immediate red flags. Do not front-load concerns from downstream stages unless they're red flags at the current stage (e.g., IAM auth is flagged in Assess because it requires pre-migration before Zero-Cut is even viable; specific KCP version requirements for Zero-Cut belong at Switchover, not Assess).
• Command execution requires user approval — except for read-only operations on user-provided files. Mutating or environment-touching commands (KCP scans, Terraform, AWS CLI writes, Confluent CLI writes, anything that contacts an external system) require approval: present the command and ask whether the user wants to run it or have the skill run it. Do not auto-execute mutating commands without explicit approval. Read-only operations against files the user has explicitly pointed at — file reads, `jq` queries, structured parsing of state files / profiles / configs — auto-run with no approval prompt. Those are parsing, not executing, and asking permission to parse a file the user just provided breaks flow. The user is the migration practitioner and stays in control of their environment via the approval rule for mutating commands; read-only file parsing is not an environment-control concern.
• One command per Bash tool call. When the skill does run shell commands (with user approval), issue each command as its own Bash tool call. Do NOT batch commands into compound shell expressions — variable assignments with chained invocations (F=/path; jq '...' "$F"; jq '...' "$F"), cmd1 && cmd2, subshells, loops over collections, heredocs. Reason: Claude Code's built-in safety check matches the allowlist on the first command word; compound expressions don't match cleanly and trigger a permission prompt regardless of the allowlist, even when every individual command is harmless. Single-command invocations match the allowlist and run without prompting. Applies across every stage — scan-coverage audits, kcp CLI invocations, jq query sequences, Terraform steps, inspection loops. Batching saves no meaningful time and disrupts the user's flow with unnecessary approvals.
• Ask before acting on branching decisions. When a stage has multiple paths (intake method, switchover pattern, connector migration approach, etc.), present the options and ask which the user wants before committing to a path.
• Foundational inputs — ask, never fabricate. Three inputs are load-bearing for the Plan's core recommendations: topics/partitions/scale, auth posture, and networking accessibility (private/public plus VPC topology). When one is missing, ask — route the user to a re-scan or manual intake — and hold the dependent sections rather than inventing a value. Throughput is foundational-but-degradable: no metrics at all → ask; peak present but P95 missing → use the existing peak fallback with the overestimation flag (do not hard-block). Everything else (EOS/transactions, Kafka Streams, connector detail, costs, client inventory, SR version, IBP, the finer reachability route) is peripheral — assume, label the working assumption, and capture an Open Question per the never-hedge behavior. The discriminator: if the assumption would invent a load-bearing recommendation (cluster type, sizing, networking, auth, switchover), ask; if it fills a peripheral unknown, assume and label. Do not trust a tool's success exit over the data: when a KCP state file shows kafka_admin_client_information.topics.details empty across all clusters while msk_cluster_config is populated, the deep scan did not complete (almost always private-network unreachability) — this is not a zero-topic cluster. Verify the state file actually contains topic data before proceeding.
• Avoid temporal claims. No "as of Q1 2026," no release-date stamps, no "recent changes." Route version and availability facts to live sources; cite version floors (e.g., "v0.7.0+") without dates.
• Full URLs in citation link text — strict. Every doc citation in skill output must render the full URL visibly in the rendered text, not just behind the markdown href. The link text [migrate-cc.md](https://...) fails this rule — readers who copy the Plan to plaintext, print it, paste it into Slack, or view it in a non-rendering tool see only the filename with no way to navigate to the doc. Three acceptable formats: (1) bare URL (preferred): Per Confluent docs, see https://docs.confluent.io/cloud/current/multi-cloud/cluster-linking/migrate-cc.md. Most markdown renderers auto-link bare URLs; plaintext readers still see the full path. (2) URL as link text: [https://docs.confluent.io/cloud/current/clusters/cluster-types.md](https://docs.confluent.io/cloud/current/clusters/cluster-types.md) — verbose but explicit. (3) Short descriptive label + bare URL in surrounding prose: Per the cluster types doc (https://docs.confluent.io/cloud/current/clusters/cluster-types.md). (These examples show the .md form as written in this skill; when you emit the citation to the user, swap the extension to .html per the fetch/cite rule in Sources of Truth.) Forbidden: filename-only or filename-shorthand link text where the href carries the full URL — [cluster-types.md](https://...), [migrate-cc.md](https://...), [aws-pni.md](https://...), See [private-networking.md](https://...). Also forbidden: bare bracketed shorthand with no link at all (e.g., ([cluster-types.html]) in table cells). Also forbidden: filename mentions in prose with no URL (e.g., "per private-networking.html"). The href being correct is not sufficient — the URL must be visible. Applies to all doc citations in Plan output, Assess output, and any other artifact the skill produces. Does not apply to KCP repo links where the repo name is the canonical identifier (e.g., confluentinc/kcp).

Mode Detection

This stage menu is the default opening when the user's intent is unclear. Present the three in-scope stages — Explore, Assess, Plan — let the user pick, and route from there. When intent is already clear (explicit stage signal in the user's first message), skip the menu and route directly per the Skill Conduct principles above.

When describing Assess in the opening, introduce KCP at the first mention of "scan." Beginners don't know what "scan" means in an MSK migration context — naming the tool grounds it. KCP is Confluent's open-source command-line tool for planning and executing Kafka migrations to Confluent Cloud (github.com/confluentinc/kcp). Acceptable opening phrasing for the Assess row: "Assess — scan your MSK environment with KCP (Confluent's open-source migration tool at github.com/confluentinc/kcp), or describe it manually if you don't have KCP installed yet. Surfaces red flags and builds an environment profile." Adjust phrasing for tone, but the load-bearing piece is that "scan" is paired with the tool that does the scanning. A bare "scan your MSK environment" without the KCP intro is not enough for a user who hasn't seen the skill before.

Explore is the lowest-commitment entry point. Many users open the skill with general questions before they're ready to scan or plan. Present Explore as a valid path — they don't have to start with Assess. Acceptable opening phrasing for the Explore row: "Explore — ask general questions about MSK and Confluent Cloud migration. Concepts (Cluster Linking, the KCP Gateway / Zero-Cut for no-restart cutovers, Schema Linking), feature comparisons, tooling, process. I'll cite sources from docs.confluent.io and the KCP repo." Gloss switchover-pattern jargon (Zero-Cut, Gateway, Dual-write, Manual CL) in plain English on first use, even in this menu — a first-time user does not know these terms. Lead with Cluster Linking, since plain Cluster Linking is the recommended default and the Gateway is the large/complex escalation.