Agent Skills have become an open standard adopted across Claude Code, Codex, Gemini CLI, Cursor, and others. The pattern is straightforward: a markdown file with frontmatter metadata and step-by-step instructions that any compatible agent can discover and follow. Projects like kagent (CNCF sandbox) already load skills from Git repositories, and the Azure Kubernetes Service team ships official agent skills alongside their MCP server. The idea of pairing an MCP server for rich server-side operations with lighter-weight skills for local CLI workflows is becoming a common pattern in the Kubernetes operations space.
Agentic skills for the StreamsHub stack could cover a wide range of workflows across the projects we maintain and support:
- Diagnosing and troubleshooting Strimzi-managed Kafka clusters, connectors, bridges, and MirrorMaker deployments
- Investigating issues with the StreamsHub Console (deployment health, API connectivity, metrics pipeline)
- Debugging Kafka Streams applications (state store problems, rebalancing issues, topology misconfigurations)
- Cross-component workflows like tracing schema compatibility issues across Kafka and Apicurio Registry, or diagnosing end-to-end message delivery failures that span producers, brokers, and consumers
- Operational tasks like assessing upgrade readiness, auditing security configurations, and analysing cluster capacity
Skills make this kind of structured knowledge portable and accessible to anyone working with the stack, whether they are running production clusters or building applications in a development environment.
What already exists
The StreamsHub MCP server for Strimzi already encodes a significant amount of this knowledge. It has 13 prompt templates that are structured, multi-step diagnostic workflows guiding an LLM through troubleshooting and analysis. These cover cluster diagnosis, connectivity troubleshooting, component-specific debugging (Connect, Bridge, MirrorMaker, Topics), capacity analysis, metrics interpretation, security auditing, configuration comparison, and upgrade readiness assessment.
This gives us a head start, but these workflows are currently only accessible through MCP clients connected to a running MCP server. That works well when the server is deployed, but there are plenty of situations where it is not available: local development, quick investigations, clusters without MCP infrastructure, or engineers who simply prefer working locally with kubectl. Skills would make this knowledge available without requiring the MCP server to be running.
How to deliver this sustainably
There are a few questions to work through.
Where do skills live?
Should skills live in the MCP repository alongside the prompt templates or in a dedicated streamshub-skills repository? A separate repo would let skills evolve independently, make it easier for users to consume them without pulling in the MCP server codebase, and provide a natural home for skills that go beyond Strimzi diagnostics. It would also make community contributions more approachable. However, there is possibility of Skills and MCP Prompts overlapping.
How do we handle the overlap with MCP prompts?
For the Strimzi diagnostic workflows, the same knowledge applies regardless of whether the data comes from an MCP tool or a local CLI command. There are a few ways to handle this:
-
Extract the diagnostic logic into a shared format (something like runbook templates) that can be consumed by both the MCP server at runtime and a build step that generates CLI-oriented skills. This keeps one source of truth but requires a templating mechanism to handle the differences between MCP tool calls and CLI commands, and it requires CLI output to be handled in a way that is compatible with the MCP tool's curated responses.
-
Keep the MCP prompts as the authoritative source and have a separate skills repository import or adapt the diagnostic knowledge. The skills repo would own the CLI-specific instructions and could also host skills that have no MCP equivalent.
-
Accept the duplication and develop skills independently. The argument here is that CLI tool outputs are fundamentally different from MCP tool responses (full Kubernetes resource JSON vs curated DTOs, raw log streams vs filtered/redacted logs, point-in-time metrics scrapes vs time-range queries). Trying to template across these differences might create more complexity than it saves, and independent skills can be optimised for the CLI experience.
Each of these has tradeoffs. Shared sources avoid drift but add coupling and build complexity. Importing from the MCP prompts gives flexibility but needs a stable contract between the two. Independent development is simplest to start but risks the diagnostic procedures diverging over time, which is exactly the kind of drift that makes runbooks unreliable.
Scope and prioritisation
Should we start with a narrow set of Strimzi diagnostic skills and expand from there, or plan the repository structure and contribution model for the full stack from the beginning? Starting narrow gets something useful into people's hands quickly, but retrofitting a broader scope later could be awkward.
Discussion
- What kinds of skills would be most valuable to start with?
- Where should skills live, and how should they be distributed?
- For the diagnostic workflow overlap, which approach best balances sustainability against complexity?
- Are there other projects in the Kafka ecosystem that have tackled similar knowledge-sharing problems we could learn from?
Agent Skills have become an open standard adopted across Claude Code, Codex, Gemini CLI, Cursor, and others. The pattern is straightforward: a markdown file with frontmatter metadata and step-by-step instructions that any compatible agent can discover and follow. Projects like kagent (CNCF sandbox) already load skills from Git repositories, and the Azure Kubernetes Service team ships official agent skills alongside their MCP server. The idea of pairing an MCP server for rich server-side operations with lighter-weight skills for local CLI workflows is becoming a common pattern in the Kubernetes operations space.
Agentic skills for the StreamsHub stack could cover a wide range of workflows across the projects we maintain and support:
Skills make this kind of structured knowledge portable and accessible to anyone working with the stack, whether they are running production clusters or building applications in a development environment.
What already exists
The StreamsHub MCP server for Strimzi already encodes a significant amount of this knowledge. It has 13 prompt templates that are structured, multi-step diagnostic workflows guiding an LLM through troubleshooting and analysis. These cover cluster diagnosis, connectivity troubleshooting, component-specific debugging (Connect, Bridge, MirrorMaker, Topics), capacity analysis, metrics interpretation, security auditing, configuration comparison, and upgrade readiness assessment.
This gives us a head start, but these workflows are currently only accessible through MCP clients connected to a running MCP server. That works well when the server is deployed, but there are plenty of situations where it is not available: local development, quick investigations, clusters without MCP infrastructure, or engineers who simply prefer working locally with
kubectl. Skills would make this knowledge available without requiring the MCP server to be running.How to deliver this sustainably
There are a few questions to work through.
Where do skills live?
Should skills live in the MCP repository alongside the prompt templates or in a dedicated streamshub-skills repository? A separate repo would let skills evolve independently, make it easier for users to consume them without pulling in the MCP server codebase, and provide a natural home for skills that go beyond Strimzi diagnostics. It would also make community contributions more approachable. However, there is possibility of Skills and MCP Prompts overlapping.
How do we handle the overlap with MCP prompts?
For the Strimzi diagnostic workflows, the same knowledge applies regardless of whether the data comes from an MCP tool or a local CLI command. There are a few ways to handle this:
Extract the diagnostic logic into a shared format (something like runbook templates) that can be consumed by both the MCP server at runtime and a build step that generates CLI-oriented skills. This keeps one source of truth but requires a templating mechanism to handle the differences between MCP tool calls and CLI commands, and it requires CLI output to be handled in a way that is compatible with the MCP tool's curated responses.
Keep the MCP prompts as the authoritative source and have a separate skills repository import or adapt the diagnostic knowledge. The skills repo would own the CLI-specific instructions and could also host skills that have no MCP equivalent.
Accept the duplication and develop skills independently. The argument here is that CLI tool outputs are fundamentally different from MCP tool responses (full Kubernetes resource JSON vs curated DTOs, raw log streams vs filtered/redacted logs, point-in-time metrics scrapes vs time-range queries). Trying to template across these differences might create more complexity than it saves, and independent skills can be optimised for the CLI experience.
Each of these has tradeoffs. Shared sources avoid drift but add coupling and build complexity. Importing from the MCP prompts gives flexibility but needs a stable contract between the two. Independent development is simplest to start but risks the diagnostic procedures diverging over time, which is exactly the kind of drift that makes runbooks unreliable.
Scope and prioritisation
Should we start with a narrow set of Strimzi diagnostic skills and expand from there, or plan the repository structure and contribution model for the full stack from the beginning? Starting narrow gets something useful into people's hands quickly, but retrofitting a broader scope later could be awkward.
Discussion