Choose what to build
Start with the outcome, not the API.
“I want my agent to do X—build Y”
| I want… | Build… | Why this surface fits |
|---|---|---|
A human to type /seeds hours and receive a local answer | An extension slash command | The command handler can answer without asking a model. |
| The model to query inventory or reserve a specific item | A model-callable tool | It has a parameter schema, structured results, cancellation and errors. |
| Several commands, tools and lifecycle handlers to share one domain | An executable extension | One default factory registers the related capabilities. |
| A key chord to insert a useful phrase or open a local view | An extension keyboard shortcut | It is an operator convenience, not a model tool. |
A startup option such as --seed-quiet | An extension CLI flag | The extension declares the flag before the CLI’s extension-aware argument pass. |
| To inspect, block or transform a tool call | An extension event handler | tool_call and tool_result are the supported interception surfaces. |
A slash command is not a tool the model can call. Register a tool when the model needs a permanent domain capability. Share a domain function between the command and tool rather than asking the model to “run the slash command.”
“Human command” also does not mean “cryptographically proven human keystroke.” An SDK or RPC host can deliberately submit slash-command text through the command-dispatch path. Extensions run in-process; this workbook’s authorization examples are domain checks, not a sandbox.
When code is unnecessary
| I want… | Build… | Important boundary |
|---|---|---|
| A reusable instruction such as “summarize a fictional field observation” | A prompt template | It expands text; it does not itself execute a TypeScript factory. |
| A named text workflow invoked through a slash command | A file-based slash command | Markdown command expansion is different from registerCommand() executing code locally. |
| A reusable body of expertise, instructions and supporting files | A skill | Discovery makes guidance available. It does not automatically execute every script in the skill directory. |
| Standing or conditionally applied instructions | A rule | Rules guide model behavior. They are not filesystem or network enforcement. |
| Different colors and visual styling | A theme | A theme changes presentation, not tool authority. |
| A different input-editor frame | An extension composer shape | A shape is executable rendering code, separate from a theme. |
When the integration belongs elsewhere
| I want… | Build… | Important boundary |
|---|---|---|
| Only a model-callable function, especially in an existing tool package | A standalone custom tool | Its factory returns tools, and its legacy execute argument order differs from native extension tools. |
| To maintain an existing event-only integration | A legacy hook, or migrate it to an extension | JS/TS hook factories can enter the extension loading pipeline. New combined integrations are usually clearer as extensions. |
| A new model endpoint, transport or login flow | A model-provider registration | This requires real provider configuration. Registering metadata does not prove inference works. |
| Tools or resources supplied by a separate process or remote service | An MCP server | The server owns a protocol endpoint; the OMP client connects to it. |
| To distribute extensions, tools, commands and optional features together | A plugin bundle | A package manifest selects entries. Installation, discovery and execution remain distinct steps. |
| To embed OMP in an application | An SDK host with inline extension factories | The host owns session creation, runtime initialization, UI and disposal. |
| To expose a Gemini-style extension description | A declarative gemini-extension.json manifest | In this snapshot, it is a metadata capability—not an automatic launcher for tools, factories, context or MCP servers named inside it. |
There is overlap by design. A plugin may contain an executable extension, a skill and a prompt. An executable extension may register a tool and a human command. An MCP tool may ultimately appear in the same tool registry as a local tool.
The useful question is always:
Which component discovers this file, which component executes it, and which interface can actually invoke the resulting capability?
The workbook’s route
Three projects carry the main progression:
- Seed Desk: welcome and inventory: a volunteer and an agent learn the same fictional desk information.
- Seed Desk: reservations: reads become revision-checked, branch-aware actions.
- Review Desk: a release note is inspected, edited, accepted, rejected or cancelled—never published.
- Package Lab: a notebook moves from one file to helpers, a manifest and SDK embedding.
Focused laboratories then cover native UI, interception, session navigation, background delivery, providers, resources and file fallbacks.
Use the public feature reference and all 46 events as lookup chapters.
How to read claims
This workbook uses three labels:
- Observed: a completed check is recorded in the supplied execution report.
- Source-backed: the behavior follows from the supplied implementation or public type contract.
- Exercise: a proposed experiment or new small example. Its expected result is explained, but it is not added to the recorded proof count.
The stories use fictional people and data. The observations describe the recorded checks, not real seed-library operations, a real release, or a provider account.
The workbook website and its downloads do not operate your OMP session. There is no tutorial-browser control API implied by these lessons.
Extensions inside those boundaries · Source chapter: extensions/choose-what-to-build. Original evidence remains scoped to its recorded snapshot.