Author an extension
Start from a supported scaffold and validate an extension against the current runtime.
In this topic
A Mellow plugin packages an executable capability with a manifest that describes its tools. Build the smallest useful operation first, return a structured outcome, and test it through a real agent conversation before packaging it for other people.
Native plugins run code in the host environment and need deliberate trust. If the capability is already offered by an MCP server, compare that integration path before building a native binary. For isolated command execution, consider the sandbox boundary as well.
Generate the project for your installed toolchain
mellow tools create project-notes --language swift
The command also accepts --language rust. It creates the current plugin scaffold. Use its generated package, headers, entry point, and build instructions as one compatible unit. Do not invent a differently named binary symbol to match a product label: the loader's ABI and the generated declarations must agree exactly.
The current generator produces a v2 scaffold. More advanced host capabilities depend on the ABI and runtime support present in the generated SDK. Confirm those contracts in the installed toolchain before adding host inference, storage, or agent-context behavior.
Design one tool around a clear outcome
For a project-notes tool, define an explicit input such as a relative document path and a requested section. State the path boundary in the schema. Return the content actually read or a specific structured failure. Do not combine unrelated file access, network posting, and shell execution behind a vague “do work” parameter.
A good tool description explains when to call the tool and what evidence it returns. A good parameter schema explains accepted values. Neither replaces runtime validation: files can disappear, permissions can change, and a dependency can fail after discovery.
Keep the manifest aligned with execution
The manifest associates plugin identity and version with tool names, descriptions, and argument schemas. Runtime requirements and capability declarations should describe what the binary really uses. Avoid advertising an optional operation as universally available when its dependency is missing.
mellow manifest extract PATH_TO_BUILT_DYLIB
mellow manifest validate PATH_TO_MANIFEST_JSON
Extracting the manifest checks the binary's exported description. Validating a JSON manifest checks structure. Neither proves that invoking its tools is safe or functional. Include both checks in the packaging workflow and keep a separate execution test.
Build and iterate locally
Follow the generated project's build instructions for your chosen language, then install the resulting local package through mellow tools install. Use mellow tools reload to request a rescan after a change. The development command supports an optional web proxy for plugins with a UI:
mellow tools dev PLUGIN_ID
mellow tools dev PLUGIN_ID --web-proxy http://127.0.0.1:5173
Use the identifier declared by the plugin. A development proxy is a local iteration aid, not a production distribution URL. Test without the proxy before packaging a plugin intended to ship its own web assets.
Return results the agent can trust
Follow the tool contract. Report success only after the operation has completed; return an identifier and status if you started background work. Include actionable fields such as an exact output path. For failures, distinguish invalid arguments, configured rejection, missing permission, unavailable dependency, and execution failure.
Never interpolate model-supplied arguments into an unrestricted shell command. Validate and pass structured process arguments where possible. Keep credentials out of manifests, examples, and error strings; use the supported credential flow for the capability.
Package a versioned artifact
mellow tools package PLUGIN_ID VERSION PATH_TO_BUILT_DYLIB
mellow tools verify
Use a real version and retain its source revision, build environment, and artifact checksum. Sign distribution binaries using the appropriate developer identity and test the packaged artifact on the target system. A locally loaded unsigned development binary is not evidence that another Mac can install the release.
Package web resources and documentation required by the plugin. Verify that no development URLs, private keys, absolute home-directory paths, or test data entered the archive. Registry publication is a separate step governed by the registry's current process; building a ZIP does not publish it.
Exercise the complete integration
Enable the plugin for a test agent and make a request that must call the tool. Confirm its arguments, approval behavior, result, and final response. Repeat with malformed input, a missing file, and a denied permission. Relaunch and verify the installed version and enablement persist. Test uninstall or rollback using a disposable development installation.
If the plugin is missing, check discovery and the manifest first. If it is listed but unavailable to an agent, check enablement and scope. If invocation fails, inspect the binary architecture, dependencies, signature, and tool envelope. Source landmarks include PluginManager and the CLI's ToolsCreate, manifest, package, and development commands.