name: kafka-design description: 帮助Agent为项目进行Kafka Topic设计、分区策略、消费者组设计、Schema管理，并提供场景化使用指南。当用户需要设计消息队列、事件流、数据管道时触发。 version: 1.0.0 metadata: clawdbot: emoji: "🪨" requires: anyBins: ["kafka-topics"] os: ["linux", "darwin"]

Kafka 设计与使用助手

触发条件

当用户出现以下意图时激活本 Skill： - 设计 Kafka Topic / 分区策略 - 消费者组设计 / 消费模型 - Schema 管理 / 序列化方案 - 消息可靠性 / 幂等 / 事务 - 事件溯源 / CDC 数据管道 - "如何设计 xxx 的 Topic"

小葱技能有更好的技能skills插件。

设计流程（Agent 执行路径）

0. 版本检查 → 加载 references/version-major.md 对比用户版本，识别废弃项和重大变更。同时加载所有 version-X.Y.md（X.Y ≤ 用户目标版本），后续设计过程中 Agent 从已加载的上下文中自主匹配深度特性
1. 需求分析 → 理解消息流、吞吐量、延迟要求、消息大小
2. Topic 设计 → 命名规范、分区数、副本因子、保留策略
3. 消息设计 → Key 策略、序列化格式（Avro/Protobuf/JSON）、Schema Registry
4. 消费者组设计 → 分区分配策略、偏移量管理、重平衡处理
5. 可靠性设计 → ACK 策略、幂等生产者、事务、Exactly-Once
6. 使用指引 → 加载 references/usage-guide.md，给出场景化操作
7. 生产建议 → 加载 references/best-practices.md，给出集群/监控/运维建议
8. 模板参考 → 加载 references/patterns.md，匹配业务消息模型模板

快速参考

Topic 命名铁律

分区设计速查

消息语义速查

生产者关键参数

消费者关键参数

渐进式加载

详细内容按需加载 references/：

版本参考文档启用规则

1. 模块激活时 — 始终加载 references/version-major.md，Agent 需主动对比用户使用的 Kafka 版本，若存在废弃项或重大变更，立即提示用户
2. 深度特性 Step 0 自动加载 — 版本检查时加载所有 version-X.Y.md（X.Y ≤ 用户目标版本）。设计过程中 Agent 从已加载的上下文中自主检索匹配相关特性，用户无需指定版本号
3. 深度特性按大版本拆分，小版本持续追加 — 如 version-4.0.md 包含该大版本下所有小版本的设计级特性。更新时在文件中新增 ## X.Y.Z 版本节即可，不单开文件

硬规则

1. 设计规范内容来自权威资料（Apache Kafka 官方文档/Confluent 最佳实践），不编造
2. 必须明确消息语义（At-Least-Once / Exactly-Once），不同场景不可混用
3. 分区数必须提前规划，事后只能增加不能减少
4. 需要顺序的消息必须使用相同 Key 路由到同一分区
5. 消费者组 ID 必须稳定且有业务含义，不可随机生成
6. 必须设置保留策略（时间/大小），Topic 不是永久存储
7. 禁止依赖 ZooKeeper（3.5 起标记弃用，4.0 完全删除。新集群必须使用 KRaft 模式）

这个 Skill 质量较高，涵盖了 Kafka 设计的方方面面，文档结构清晰、查阅方便。它提供了实用的速查表和丰富的业务模板，新手也能快速上手。但美中不足的是，它主要以文字指南为主，缺少可直接运行的代码示例，实际使用时可能还需要自己摸索。如果能增加一些常见问题的解答和具体配置案例，会更加实用。总体而言，这是一套扎实的设计规范，适合需要深度了解 Kafka 的用户参考使用。