Kafka Java client skill

[Dave Troiano (davetroiano)]

Description

Add skill for developing Kafka client apps in Java.

Docs

• If adding a new skill, I have reached out to reviewers to make sure the docs are updated to reflect the new skill.

Testing

• Evals pass at 90%+ threshold

Review

• /confluent-skill-reviewer has been run
• [] SME reviewer identified if adding a new skill
• [] DTX/DevRel reviewer assigned

[Copilot]

Pull request overview

Adds a new developing-kafka-java-client skill to this repo, including reference scaffolding templates and eval coverage, and updates existing docs/trigger text to avoid overlap between the Python and Java Kafka client skills.

Changes:

• Add the developing-kafka-java-client skill with detailed hard-gate requirements gathering and project scaffolding guidance (Maven/Gradle; Cloud/Docker/WarpStream; Avro/JSON Schema/Protobuf; Consumer vs Share Consumer).
• Add Java skill reference templates (KafkaConfig, producer/consumer examples, schema rules, docker-compose, build files) and evals.
• Update the Python skill description to explicitly avoid triggering for Java-client requests; add the Java skill to the root README skills list.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
README.md	Adds the new Java client skill to the repo’s skill listing.
skills/developing-kafka-python-client/SKILL.md	Adds anti-trigger guidance to avoid overlap with the new Java client skill.
skills/developing-kafka-java-client/SKILL.md	New Java Kafka client skill instructions (scope, gates, scaffolding flow, environment/schema/build variants).
skills/developing-kafka-java-client/evals/evals.json	Adds evals defining expected behavior/output for the Java client skill.
skills/developing-kafka-java-client/references/KafkaConfig.java	Reference implementation for config loading + Kafka/SR connectivity verification.
skills/developing-kafka-java-client/references/AvroProducer.java	Reference async Avro producer template.
skills/developing-kafka-java-client/references/AvroProducerSync.java	Reference synchronous Avro producer template.
skills/developing-kafka-java-client/references/AvroConsumer.java	Reference Avro consumer template using Schema Registry + wakeup shutdown.
skills/developing-kafka-java-client/references/AvroShareConsumer.java	Reference Share Consumer API template (Queues for Kafka) with explicit ack.
skills/developing-kafka-java-client/references/JsonSchemaProducer.java	Reference JSON Schema producer template.
skills/developing-kafka-java-client/references/JsonSchemaConsumer.java	Reference JSON Schema consumer template.
skills/developing-kafka-java-client/references/pom.xml	Maven reference build with Confluent repo + serializer deps + Avro codegen + test deps.
skills/developing-kafka-java-client/references/build.gradle	Gradle reference build with Confluent repo + serializer deps + Avro codegen plugin.
skills/developing-kafka-java-client/references/docker-compose.yml	Local Docker reference for Kafka + Schema Registry.
skills/developing-kafka-java-client/references/value.avsc	Example Avro schema used by the reference templates.
skills/developing-kafka-java-client/references/value.schema.json	Example JSON Schema used by the reference templates.
skills/developing-kafka-java-client/references/schema-generation-rules.md	Rules for generating schemas (Avro default + JSON Schema alternative).
skills/developing-kafka-java-client/references/readme-template.md	README template guidance for generated projects.
skills/developing-kafka-java-client/references/share-consumer.md	Guidance for when/how to use the Share Consumer API (Queues for Kafka).
skills/developing-kafka-java-client/references/multi-event-guide.md	Guidance for multi-event topics (union schemas / oneOf) when needed.
skills/developing-kafka-java-client/references/warpstream-optimization.md	WarpStream-specific client tuning reference for Java and librdkafka clients.
skills/developing-kafka-java-client/references/AppTest.java	Unit test template for generated projects (offline tests via mocks / schema validation).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Lianet Magrans (lianetm)]

Thanks Dave Troiano (@davetroiano) !

[Lianet Magrans (lianetm)]

similar, consumer has the whole story of automatic commit vs manual commit, sync and async..just raising in case it's something we want to add an md similar to this but for the regular consumer

[Dave Troiano (davetroiano)]

👍 I added coverage for these topics in the consumer reference

[jmathai-confluent]

I have a question about ownership of code samples in skills. Normally the docs team or eng team is responsible for fixing bugs or updating code samples. What's the ownership model for skills?

Is it an option to link to the relevant docs with this content?

cc d8joseph

[Dave Troiano (davetroiano)]

The general model and direction that I think this is heading in is that product / eng both contribute and maintain, with the agent-skills repo maintainers doing the requisite notifications and reviews etc. This one is a little different because I'm contributing so I would expect to continue to be involved not in a "this is my baby" reason but a "I added this so it's only fair I have a hand in maintaining it until there's agreement to 'take it over'". probably not the best answer but it's kinda where we're at given that the maintainers want to get to that cleaner ownership model but at the same time we are bootstrapping the repo so there are in between cases like this.

[Dave Troiano (davetroiano)]

regarding public docs, we do link to docs in the repo. I tend to be a bit hesitant since docs weren't necessarily written with agent skills in mind which might have some quality / control issues when it comes to skill effectiveness, token usage, and potential for a rug pull with a docs change that isn't keeping their spot as a dependency in mind. There are some other things that I think need some figuring out. e.g., docs publishes markdown files to be agent friendly but if those markdown files contain relative links elsewhere on Confluent Docs, they'll be html. over time we might get more comfortable with the idea of skills pointing out to canonical references more often but the comfort isn't there today at least speaking for myself. even today if I look at the docs page I'd naturally point to for this, it'd be https://docs.confluent.io/kafka-clients/java/current/overview.md which contains html links as well as links over to Confluent Developer examples. it's really human-intended.

[jmathai-confluent]

I think this might have been derived from the Warpstream docs - should this be a skill on its own?

[Dave Troiano (davetroiano)]

We decided when first adding warpstream guidance that we'd overlay guidance "inline" per skill though we acknowledged we need a better way to generalize. Separate skill may be the way forward but it's just one option that would probably have some tradeoffs. As one example downside, I think we should allow for the possibility that users will be surgical in terms of which skills they choose to install rather than accepting the kitchen sink. so it'll need some tinkering and tradeoff weighing. for now in this PR I think we should stick with this pattern and then I can take on revisiting the general problem and how we want to handle it now that it's getting more obviously problematic when it comes to warpstream overlay guidance.