Skip to main content
Bonsai is a small stable core plus a set of extensions. That isn’t a description of a future plugin ecosystem — it’s how Bonsai is built today. Gmail, GitHub, Notion, Slack, and the rest are plugins loaded through the same contract your own code would use. There are two ways to extend Bonsai, and they differ in one thing that matters more than any other: whether you are shipping instructions or shipping code.

Skills

A skill is reusable instruction — the knowledge of how to do something properly, written down once so Bonsai applies it every time instead of you re-explaining it. Skills don’t grant Bonsai any new capability; they shape how it uses the capabilities it already has. A skill is a directory with a SKILL.md in it:
In Bonsai, ask the assistant to read skill://skills/authoring before creating or improving a skill. That guide owns descriptions, structure, references, specializations, and verification. The example above is a source file for a repository; when Bonsai creates a personal skill through skill://, its tools serialize the file from structured fields.

Where skills come from

1

Your own machine

Drop the skill directory in ~/.kay/agent/skills/<name>/SKILL.md and it’s available to Bonsai.
2

A project you're working in

A .kay/skills/ directory inside a project applies whenever Bonsai is working in that project — this is how a team ships its conventions alongside its code. Bonsai also reads .claude/skills/, so an existing Claude Code skill library works as-is.
3

A shared repository

Ask Bonsai to add a skill source and point it at a git repository. Bonsai stages it and asks the user to approve the source before syncing anything from it. Approved sources can later be refreshed, revoked, or removed from the Skills sidebar.

Plugins

A plugin is a package that Bonsai loads at startup and that can contribute:
  • Tools the agent can call
  • Integrations — a connected service with its own sign-in, so the agent can reach an external API on the user’s behalf
  • Addressable resources under its own scheme://, which the agent browses and reads the same way it reads anything else
  • Skills bundled with the plugin, carrying the judgment its tools need
  • Pages — full React apps hosted inside Bonsai’s workspace
First-party plugins use exactly these contribution points, which is the intent: the contract is dogfooded rather than designed in the abstract.

How a user installs one

Plugins are distributed as git repositories. Use the App Store to add a source, trust it, and install individual plugins.
1

Point Bonsai at the repository

Ask Bonsai to add a plugin source, or open App Store → Sources → Add source and enter the repository link.
2

The user trusts the source

Review the source in App Store → Sources. Granting trust is a decision only a human can make in Bonsai’s own UI — the agent can stage a source and read its status, but can never trust one.
3

Install the plugin

For a marketplace catalog, choose Get on the plugin under App Store → Browse. For a plain Git repository, open the source under App Store → Sources and choose Turn on on the plugin. Either action installs and enables that plugin; trusting its source does not install every item it contains. Installed plugins appear under App Store → Installed, where you can turn them off or remove them.
An installed plugin runs as in-process code, not in a sandbox. Trust only sources whose code you are willing to run, and install only the plugins you need. Source trust and each plugin’s install decision are separate.

The approval model

One principle runs through all of the above, and it’s worth understanding before you design anything: the agent can propose, but only a human can grant. Bonsai’s agent can stage a source, request a permission, or ask to connect an app. It cannot grant source trust or approve its own permission requests. Putting a plugin in ~/.kay/plugins/ makes it discoverable, not enabled: it still needs an explicit install decision in App Store → Installed. Build with that grain rather than against it. An extension that needs a capability should ask for it explicitly and describe honestly what it does with it, because that description is what the user reads when deciding.

What isn’t public yet

Bonsai is in private beta, and so is the developer surface:
  • The plugin SDK is published, but not publicly. @yaklabs-ai/plugin-sdk and @yaklabs-ai/plugin-protocol ship to GitHub Packages at matched versions, and both are private — installing them needs membership of the yaklabs-ai GitHub organization. So plugin authoring is limited to Yak Labs and design partners for now. Installing an already-built plugin from a repository works for anyone.
  • MCP servers are not available on the released build. Support for connecting external Model Context Protocol servers exists and is in internal testing, but it doesn’t ship in the current public release.
If you’re building something on Bonsai and need the SDK, get in touch — the beta is small enough that we work with people directly.

Quickstart

Install Bonsai and run your first task.

Bonsai home

What Bonsai is and who we build it for.