write-zot-extension

Writing a zot extension

Use this skill when the user asks for help building a zot extension — a new slash command, a new tool the LLM can call, an audit hook, or a permission gate. Skim this whole skill first, then collaborate with the user on the specific extension they want.

What an extension is

A zot extension is an external executable that zot launches as a subprocess and talks to over its stdin/stdout in newline-delimited JSON. It can be written in any language that can read/write JSON lines from stdio: Go, TypeScript (via tsx), Python, Rust, shell with jq, anything. Crash isolation is automatic; one bad extension never takes down zot.

Three things an extension can do (any combination):

1. Slash commands — register /foo so the user can run it from the input. The handler returns a "prompt" (submitted to the agent), an "insert" (text dropped into the editor), a "display" (one-shot styled note in the chat), or a "noop".

2. Tools — register tools the LLM itself calls. Schema is JSON Schema; zot routes the model's tool_call to the extension's tool_result. Same lifecycle as built-in tools (read/write/edit/bash/skill).

3. Lifecycle hooks — subscribe to events (session_start, turn_start, tool_call, turn_end, assistant_message) for telemetry / audit / custom UI, or intercept tool calls before execution to refuse dangerous patterns.

On-disk layout

Each extension lives in its own directory:

~/Library/Application Support/zot/extensions/<name>/
├── extension.json    # manifest (required)
└── <executable>      # whatever exec points at

Or project-local: <project>/.zot/extensions/<name>/. Project-local wins on name conflict.

For ad-hoc use during development, skip the install step entirely and run zot --ext PATH (repeatable: -e PATH -e PATH).

Manifest

{
  "name": "weather",
  "version": "1.0.0",
  "exec": "./weather",
  "args": [],
  "language": "go",
  "description": "current weather lookups for any city",
  "enabled": true
}