# Developing Genkit Tooling

> Developing 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.

- Skill name: `developing-genkit-tooling`
- Category: [Agent Building](https://www.openparable.com/skill/agent-building/1)
- Source: https://github.com/genkit-ai/genkit/blob/HEAD/skills/developing-genkit-tooling/SKILL.md
- Repository: genkit-ai/genkit (6,244 GitHub stars when collected)

## SKILL.md

# 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:verb` or `category: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.

```typescript
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 `logger` from `@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 `--stream` flag 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 `server` instance.
- **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 `options` containing `manager` (process manager) and `projectRoot`.
- **Schema**: MUST use `getCommonSchema(options.explicitProjectRoot, ...)` to ensure the tool can accept a `projectRoot` argument when required (e.g., in multi-project environments).

```typescript
// 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.

```typescript
try {
  // operation
} catch (err) {
  const message = err instanceof Error ? err.message : String(err);
  return {
    isError: true,
    content: [{ type: 'text', text: `Error: ${message}` }],
  };
}
```

---

Source: https://www.openparable.com/skill/agent-building/developing-genkit-tooling (OpenParable). Cite the canonical URL above.
