为什么你的 Genkit 工具总被人吐槽「不好用」？

为什么你的 Genkit 工具总被人吐槽「不好用」？

做 AI 应用的团队，十有八九都踩过一个坑——花了大把时间写了一个 Genkit 插件，结果团队里其他人用起来完全摸不着头脑：命令名字不规范、参数格式混乱、报错信息看不懂。

问题往往不在功能本身，而是工具的接入体验没做好。

Google Firebase 官方出的 developing-genkit-tooling 就是来解决这个问题的。它本质上是一套 Genkit 工具开发规范，告诉你怎么正确地写 CLI 命令、怎么设计 MCP 工具接口、怎么让错误处理对用户友好。

这套规范核心解决了三个问题

命名一致性。CLI 命令用 kebab-case + 冒号分隔（flow:run、eval:run），MCP 工具名用 snake_case（list_flows、run_flow）。用户和 Agent 看到名字就能猜出用法。

架构分层清晰。CLI 命令统一放在 cli/src/commands/ 用 commander 实现；MCP 工具分「静态工具」（文档类，不需要项目上下文）和「运行时工具」（需要操作项目进程），两套注册接口泾渭分明。

错误处理规范。MCP 工具遇到异常要返回 isError: true 的 content block，而不是直接抛异常——这样客户端能拿到结构化的错误信息，而不是一堆 Stack Trace。

对你的实际价值是什么

如果你在写 Genkit 相关的 CLI 工具或 MCP 服务器，照着这套规范来，你写出来的东西天然就和 Genkit 生态兼容——用户不需要额外学习你的命名逻辑，Agent 也能准确调用。

它还顺带规范了输出格式：日志用 @genkit-ai/tools-common/utils 里的 logger，支持 JSON 输出和流式输出（--stream 标志），这对于需要程序化调用工具的开发者来说非常关键。

快速上手

在你的 Genkit 项目里加载这个 Skill，然后按照规范创建命令即可。官方示例覆盖了 CLI 命令、MCP 工具注册、运行时进程管理、错误处理全链路。

属于那种「看完规范文档才发现自己以前写的都是草台班子」的类型。

GitHub 仓库直达

GitHub: https://github.com/firebase/genkit/tree/main/skills/developing-genkit-tooling