---
name: fabritorio-tool-builder
description: Build or extend a Fabritorio runtime tool — a single CLI binary plus a manifest.json that the runtime discovers by scanning a tools directory — from any coding harness (Claude Code, pi, a shell, or by hand). Use this whenever someone wants to create, build, wrap, scaffold, or extend a CLI, tool, or integration for Fabritorio: e.g. "build a Linear CLI for Fabritorio", "wrap this REST API as a tool", "add a Notion tool", "turn this script into a runtime tool", "extend the existing X tool", or anything that involves writing a manifest.json for a Fabritorio tool — even when the phrase "Fabritorio runtime tool" isn't used explicitly. Covers the Go-default static binary, the bash_cli manifest contract, credential/env-var wiring, smoke-testing, and updating tools in place.
---

# fabritorio-tool-builder

Build a **Fabritorio runtime tool**: a CLI that any Fabritorio agent can wire as a `tool` node and call natively — gated by permissions, not routed through `bash`.

The key fact that makes this skill harness-neutral: **the integration boundary is files on disk, nothing else.** There is no SDK to call and no registration step. The runtime discovers a tool by scanning a directory for an executable binary next to a `manifest.json`. So whatever can write those two files — this agent, Claude Code, pi, a CI job, or you with an editor and `go build` — produces a first-class tool. The harness is interchangeable; the manifest is the contract.

**The manifest is the product, not the binary.** A binary with no manifest is invisible: the registry won't surface it, agents won't find it in the catalog, the `tool` node won't resolve. The Go code is the easy part — the judgment is in the manifest. Its full schema, field semantics, and a worked example live in **`references/manifest.md`**; read that file when you're about to write the manifest (step 5 below), not before.

## Where things live — the one Fabritorio-specific path

The runtime scans a **tool scan root** and projects each conforming manifest into the agent tool catalog. The root is:

- `~/.fabritorio/tools/` by default, **or**
- the first colon-separated entry of `$FABRITORIO_TOOL_ROOTS`, if set.

Call it `$TOOL_ROOT`. Everything you produce lands at `$TOOL_ROOT/<name>/`. The registry rescans on every tool-catalog read (and on a tool-lookup miss during an agent build), so a freshly written tool appears without restarting the runtime.

This is the *only* path tied to Fabritorio. Use ordinary absolute paths in your harness's file tools — there's no workspace gate or tilde-expansion quirk to design around. (Those were properties of one specific in-runtime agent, not of the contract.)

## The deliverable

Three artifacts under `$TOOL_ROOT/<name>/`:

1. **Source** — `go.mod`, `main.go`, any helpers. Builds cleanly with `go build ./...`. No CGo or platform shims unless the integration genuinely needs them.
2. **Binary** — `bin/<name>`. One static file, **executable bit set** (`chmod +x`). The registry checks the exec bit and silently skips anything without it, so a tool that doesn't appear after a rebuild is almost always a permissions problem — check `ls -la bin/<name>` first.
3. **Manifest** — `manifest.json`. Shape and semantics in `references/manifest.md`. Its `name` field must equal the directory name and the binary name.

A behavioural `SKILL.md` alongside is optional — ship it only when there's *how to think about this tool* content the manifest can't carry (multi-step workflows, "reach for this vs that", domain pitfalls). For a one-verb CLI the manifest is enough; a SKILL.md would just restate it.

If any required artifact is missing, the task isn't done. Report partial state honestly ("source builds, smoke test fails on auth — needs `LINEAR_API_KEY`") rather than claiming success — the caller trusts your report literally.

## Clarify before building only when you genuinely can't default

Gate on complexity. A trivial single-verb, obvious-return CLI ("scrape this URL, return the text") → just build it. Multi-verb, ambiguous return, or unclear auth → ask once, in one batch:

1. **Verbs** — what distinct operations? Each becomes its *own* tool (`issue_list`, `issue_create`), not one `linear` with subcommands. Per-verb tools let the agent wire only what it needs and gate permissions per-verb.
2. **Return shape** — per verb, what comes back and as what (JSON array, single object, plain text)?
3. **Auth — pin the env var name.** This is the one question worth asking even when everything else is obvious. If the integration authenticates at all, the binary reads its credential from one named env var (see Credentials). That name is a contract between your manifest and whatever supplies the secret, so confirm it up front rather than inventing one: propose the conventional `<UPPERCASE_TOOL>_API_KEY` / `_TOKEN` and let the requester correct it. A later rename touches the manifest *and* the user's secret binding.

Don't ask about things this skill already settles (language, layout, manifest mechanics).

## Language: Go by default

Default to **Go**, for reasons that matter to the substrate rather than taste:

- *One static binary* — no `pip install`, venv, or `node_modules`. The tool dir is self-contained: copy it, run it.
- *Fast cold start* — agents invoke the CLI many times per session; Go subprocess startup is ~5 ms vs Python's ~100 ms+ with imports. It compounds.
- *Stdlib covers the 80% case* — `net/http` + `encoding/json` handle most REST integrations with zero external deps.

Reach for **Python only** when the integration ships a Python-only SDK that would cost more to reimplement than to wrap. Then isolate it in a `.venv/` inside the tool dir, make `bin/<name>` a shim that activates the venv and execs the entrypoint, pin `requirements.txt`, and say so in any SKILL.md. **Never Node** (same dependency problems, no offsetting win). **Never a shell script for anything non-trivial** (quoting bugs, no real JSON handling, untestable).

## Build sequence

Plain shell — run it however your harness runs commands.

```bash
# 1. Init (first time only)
mkdir -p "$TOOL_ROOT/<name>/bin"
cd "$TOOL_ROOT/<name>"
go mod init fabritorio/tool/<name>

# 2. Write main.go (+ helpers) with your harness's file tool.

# 3. Build + make executable
go build -o bin/<name> ./...
chmod +x bin/<name>

# 4. Smoke test — at least --help; ideally a dry run that loads config
#    without a network call.
./bin/<name> --help

# 5. Write manifest.json — read references/manifest.md first.