Developing Genkit Tooling
Agent Buildingdeveloping-genkit-toolingDeveloping Genkit Tooling is an Agent Skill for agent building published in the genkit-ai/genkit repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Best practices for authoring Genkit tooling, including CLI commands and MCP server tools. Covers naming conventions, architectural patterns, and consistency guidelines.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/genkit-ai/genkit/blob/HEAD/skills/developing-genkit-tooling/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/developing-genkit-tooling, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Developing Genkit Tooling
Naming Conventions
Consistency in naming helps users and agents navigate the tooling.
CLI Commands
Use kebab-case with colon separators for subcommands.
- Format:
noun:verborcategory:action - Examples:
flow:run,eval:run,init - Arguments: Use camelCase in code (
flowName) but standard format in help text (<flowName>).
MCP Tools
Use snake_case for tool names to align with MCP standards.
- Format:
verb_noun - Examples:
list_flows,run_flow,list_genkit_docs,read_genkit_docs
CLI Command Architecture
Commands are implemented in cli/src/commands/ using commander.
Runtime Interaction
Most commands require interacting with the user's project runtime. Use the runWithManager utility to handle the lifecycle of the runtime process.
import { runWithManager } from '../utils/manager-utils';
// ... command definition ...
.action(async (arg, options) => {
await runWithManager(await findProjectRoot(), async (manager) => {
// Interact with manager here
const result = await manager.runAction({ key: arg });
});
});
Output Formatting
- Logging: Use
loggerfrom@genkit-ai/tools-common/utils. - Machine Readable: Provide options for JSON output or file writing when the command produces data.
- Streaming: If the operation supports streaming (like
flow:run), provide a--streamflag and pipe output to stdout.
MCP Tool Architecture
MCP tools in cli/src/mcp/ follow two distinct patterns: Static and Runtime.
Static Tools (e.g., Docs)
These tools do not require a running Genkit project context.
- Registration:
defineDocsTool(server: McpServer) - Dependencies: Only the
serverinstance. - Use Case: Documentation, usage guides, global configuration.
Runtime Tools (e.g., Flows, Runtime Control)
These tools interact with a specific Genkit project's runtime.
- Registration:
defineRuntimeTools(server: McpServer, options: McpToolOptions) - Dependencies: Requires
optionscontainingmanager(process manager) andprojectRoot. - Schema: MUST use
getCommonSchema(options.explicitProjectRoot, ...)to ensure the tool can accept aprojectRootargument when required (e.g., in multi-project environments).
// Runtime tool definition pattern
server.registerTool(
'my_runtime_tool',
{
inputSchema: getCommonSchema(options.explicitProjectRoot, {
myArg: z.string(),
}),
},
async (opts) => {
// Resolve project root before action
const rootOrError = resolveProjectRoot(
options.explicitProjectRoot,
opts,
options.projectRoot
);
if (typeof rootOrError !== 'string') return rootOrError;
// access manager via options.manager
}
);
Error Handling
MCP tools should generally catch errors and return them as content blocks with isError: true rather than throwing exceptions, which ensures the client receives a structured error response.
try {
// operation
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
return {
isError: true,
content: [{ type: 'text', text: `Error: ${message}` }],
};
}