Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →vellum-ai/plugin-builder
Use when the user wants to build, scaffold, ship, or edit a Vellum plugin that bundles multiple surfaces (hooks, tools, skills, and more) into one installable package.
Passed 21 of 22 test cases with the skill, and 5 of 22 without it.
and 22 more in the full report
16 fixed5 passed either way1 still failing0 broke
Tokens, turns and time describe resource use, not a dollar price.
One of 16 test cases the skill fixed. Same model, same prompt, with and without the skill.
Which CLI command checks if an installed Vellum plugin is up to date and has no drift relative to its source?
| Checked | Without skill | With skill |
|---|---|---|
| The response specifies running assistant plugins inspect. | Missed | Passed |
The instructions your model reads when the skill loads.
Build on top of Vellum with plugins. A plugin bundles multiple surfaces into a single installable package that extends what an assistant can do.
Plugins are in beta. The peer-dep range you declare is what gets you load. Treat everything you write as something that can break between Vellum releases until 1.0 ships, and pin a real range.
A plugin is a directory in the assistant's workspace (<workspaceDir>/plugins/<name>/) that groups different surfaces into one cohesive capability. The assistant can build plugins directly in this folder or install one from the community via the CLI:
assistant plugins install <name>
Plugins can also be discovered and managed from the Plugins tab in the app, or searched from the CLI with assistant plugins search. The catalog is a curated allowlist that the Vellum team approves and curates.
A single plugin can contribute several different kinds of behavior. Each surface is discovered by convention from a named subdirectory. Missing directories are simply skipped, so a plugin contributes only what it ships.
| Surface | Lives in | What it does |
|---|---|---|
| Lifecycle hooks | hooks/<name>.ts | Run code at fixed points in the Assistant's lifecycle to read or transform what flows through, and broadcast progress to the UI. |
| Skills | skills/<name>/ | Directories of instructions and associated assets, scripts, and resources that the Assistant loads dynamically when relevant. |
| Model-visible tools | tools/<name>.ts | Add new tools the model can call. Plugin tools land in the same catalog as built-in tools. |
| HTTP routes | routes/<path>.ts | Serve HTTP endpoints (webhooks, integrations, callbacks) in the plugin's own /x/plugins/<name>/ namespace. |
| Apps | apps/<name>/ | Ship persistent interactive apps (dashboards, trackers, visualizations) compiled from a Preact + TSX bundle and rendered in the workspace panel. |
The two extensibility patterns serve different goals. Plugins are for distribution: you intend to share the capability, publish to the marketplace, or install it across multiple assistants. The plugin manifest (package.json), the @vellumai/plugin-api peer dependency, and the install flow exist to make a capability portable, versioned, and discoverable by others.
Direct workspace contributions are for personal extension: you simply want to extend your assistant and have no intention of distributing the work. Skip the plugin packaging entirely. Drop the file directly into the matching top-level workspace directory (/workspace/tools/<name>/ for a tool, /workspace/skills/<name>/ for a skill, etc.) and the assistant picks it up automatically. No manifest, no install step, no peer dependency. Lifecycle hooks are the one exception: they can only be contributed through a plugin, since there is no direct /workspace/hooks/ path.
Several surfaces that plugins contribute run in the same process as the main Assistant process. They can import all internal methods from the Assistant from the single public package, @vellumai/plugin-api, which is the only supported contract. Anything not exported from there is internal and can change without notice. See references/plugins.md for the full export surface.
Vellum's plugin model was designed to line up with the agent harnesses you may already use. The shared vocabulary is deliberate to be as portable as possible with the other entrants in the industry.
test cases passed, vs 5 / 22 without
More skills from the same source and nearby in the registry, with their headline benchmark lift.