Building your own toolkits

Custom toolkits are how Jootle extends to needs that no off-the-shelf toolkit covers.

This chapter is the conceptual overview. The full developer reference (JTF format, schemas, API contracts) lives in the developer docs and is intentionally not duplicated here.

When to build your own

Reasons that justify the build:

A business-specific workflow that no public toolkit handles. (“My catering business needs to track event quotes through a specific 7-stage pipeline.”)
An integration with a system unique to your work. (A custom inventory system, a niche industry tool.)
A heavily customized version of a public toolkit. (You like CRM but want to add three custom fields and rename half the labels.)

Reasons that aren’t great:

“It would be cool to build one.” Custom toolkits are real work. If there’s no specific problem driving it, you’ll abandon it.
A tweak to an existing toolkit. Most public toolkits expose configuration before they require forking. Try the settings first.

The model

A toolkit is a bundle of:

Entity types. New kinds of things your instance can track. (“Quote”, “Customer”, “Recipe”.)
Views. Sidebar entries with UI that lets you work with those entities.
Playbooks. Specific multi-step workflows your AI can run on those entities.
Goals. Schedules that keep work moving in the toolkit’s domain.
Channel adapters or connectors. Optional, for integrating with external systems.

You define these in a single file (the toolkit manifest) plus any code your toolkit needs.

The toolkit format (JTF)

JTF is the file format toolkits use. A complete toolkit is a single .jtf.json file (or directory of files, for larger toolkits) describing all of the above.

The full schema is in the developer reference (the JTF spec, not part of this handbook). The summary:

Manifest section defining the toolkit’s name, version, author, description, and dependencies on other toolkits.
Entities section defining the entity types, their fields, and their UI affordances.
Playbooks section defining the multi-step workflows.
Goals section defining the scheduled jobs.
Adapters section defining external integrations.

You can hand-write a .jtf.json if you’re comfortable with JSON. You can also have your AI help you draft one, since the schema is something it knows.

The “ask your AI to build it” path

The most common way customers build their first custom toolkit is by asking their AI.

“I run a catering business. I want a toolkit that tracks quotes through these stages: inquiry, proposal sent, accepted, in-progress, completed. Each quote has a customer, event date, headcount, and total. I want a weekly view of upcoming events.”

Your AI drafts a toolkit manifest, asks clarifying questions, and produces a working draft you can install in your instance immediately.

You then iterate: “Add a ‘deposit received’ field to quotes.” “When a quote is accepted, automatically create a project for that event.”

This “conversational toolkit building” is the easier path for non-developers. For developers, hand-writing the JSON or using a code editor is also fine.

Testing your toolkit

A toolkit you’ve built can be installed on your own instance immediately. Test it there. If it works, you have an answer to whether the design is right.

For toolkits you’d share, install on a fresh test instance to verify it works without depending on your specific data. You can spin up a test instance through the Provisioning page (if your plan includes it) or use a sandbox account.

Two ways:

Private share. Export the toolkit as a .jtf.json file and send it to someone. They install it directly. No public listing. Good for sharing with a colleague, a client, or another business.

Public submission. Submit the toolkit to the library for review. We test it, we evaluate fit, and if it’s a good fit for the broader audience, we publish it as a community toolkit. The submission flow is in Settings → Toolkits → Submit.

Submissions can be commercial (you charge a license fee) or free. If you submit a paid toolkit, the library handles licensing through your Stripe Connect account.

When to NOT build a custom toolkit

Sometimes the right answer is “this isn’t a toolkit, it’s a customization”:

A custom playbook in your instance, not bundled as a toolkit.
A custom goal with rules that match your unique need.
A specific entity type added directly through the conversation (“track customers like contacts, but with these extra fields”).

These don’t need to be packaged as a toolkit. They live in your instance.

The dividing line: if it’s only useful for you, just configure it. If it’s reusable across instances, make it a toolkit.

Where to learn more

Developer-facing references (not in this handbook):

JTF format spec. The full schema and examples.
Toolkit examples repo. A small set of working toolkits with source code.
Adapter / connector reference. For integrations with external APIs.

Ask your AI to point you at the latest links; the developer docs move occasionally as the platform evolves.

A small note on quality

Custom toolkits inherit the broader Jootle voice and behavior. The same approval gates, the same conversational interface, the same knowledge graph integration. If your toolkit’s UX feels off-pattern compared to the rest of your instance, it’s usually a sign to align with the conventions rather than fight them.

The toolkit format is generous; you can do a lot. The discipline is to do less.