Agent skill

Plugin Builder

by vellum-ai in vellum-ai/vellum-assistant

A skill your agent uses 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.

MITAuto-check passed

Install Plugin Builder

skills CLI
$ npx skills add vellum-ai/vellum-assistant --skill plugin-builder -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install vellum-ai/vellum-assistant plugin-builder --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/vellum-ai/vellum-assistant.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/plugin-builder .claude/skills/plugin-builder && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
plugin-builder
GitHub stars
1.4k
Token cost
~3.1k tokens
SKILL.md length
1,383 words
Files
10 (incl. references)
Skills in repo
108
Repo updated
First seen
Licence
MIT

At a glance

A skill your agent uses 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.

  • Works in 6 steps: What job does the plugin do? One… → Which surfaces does it ship? Pick from… → Does it need credentials? An API key,… → …
  • The user wants to build
  • SKILL.md covers What is a plugin?, The surfaces a plugin can bundle, Before you write a single file and Scaffold the directory, plus 4 more sections
  • Reaches github.com

What it does

Plugin Builder is an agent skill from vellum-ai/vellum-assistant. 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.

Its SKILL.md is about 3.1k tokens, which your agent loads only when the skill is triggered. The skill folder holds 10 other files, including reference files (for example `references/apps.md`, `references/channels.md` and `references/distribution.md`). Compatibility notes: Designed for Vellum personal assistants

The repository describes itself as: An AI Assistant that’s easy to setup, does your work 24/7, knows your preferences and gets better over time. The licence is MIT.

When your agent uses it

  • The user wants to build
  • Edit a Vellum plugin that bundles multiple surfaces (hooks
  • More) into one installable package

Example prompts

  • “/plugin-builder”

Requirements

  • Compatibility (from SKILL.md): Designed for Vellum personal assistants

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

  1. What job does the plugin do? One sentence, plain language. If you cannot write this, the plugin should not be built yet.
  2. Which surfaces does it ship? Pick from the surfaces table above. Most plugins ship one or two, not all of them. See references/plugins.md…
  3. Does it need credentials? An API key, OAuth token, or webhook secret is not a value that belongs in a .ts file. For LLM inference…
  4. Does it keep state? A plugin is fully self-contained: durable state lives in its data/ directory (InitContext.pluginStorageDir), with…
  5. Where will the source live? A GitHub repo, ideally under the user's own namespace. The marketplace entry pins to a full commit SHA.
  6. Is the user writing TypeScript or compiling ahead? In-repo Bun/Node compile on assistant start is the default. If they want a different…

What it can do on your machine

Read from SKILL.md and the folder at commit c92ead1. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Hosts in commands or code, which the agent is likely to contact:

    • github.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

  • Compatibility

    Designed for Vellum personal assistants

    From compatibility in the SKILL.md frontmatter.

Context cost

Plugin Builder loads about 3.1k tokens when it runs, and up to ~45k if it reads all its reference files. Until then it costs about 46 tokens; SKILL.md has 1,383 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~46
When it runs · the whole SKILL.md, loaded when a task matches
~3.1k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~45k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from vellum-ai/vellum-assistant at commit c92ead1, republished under its MIT licence (© vellum-ai). 1,383 words, ~3,102 tokens.

Download SKILL.mdSave it as .claude/skills/plugin-builder/SKILL.md (or your agent's skills folder). This skill also uses 9 other files; get the full folder from GitHub.
name
plugin-builder
description
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.
compatibility
Designed for Vellum personal assistants
metadata.emoji
🧩

Plugin Builder

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.

What is a plugin?

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.

The surfaces a plugin can bundle

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.

SurfaceLives inWhat it does
Lifecycle hookshooks/<name>.tsRun code at fixed points in the Assistant's lifecycle to read or transform what flows through, and broadcast progress to the UI.
Skillsskills/<name>/Directories of instructions and associated assets, scripts, and resources that the Assistant loads dynamically when relevant.
Model-visible toolstools/<name>.tsAdd new tools the model can call. Plugin tools land in the same catalog as built-in tools.
MCP serversmcp.jsonDeclare MCP servers the assistant connects on install. Their tools land as mcp__<id>__<tool> alongside workspace-configured MCP tools.
HTTP routesroutes/<path>.tsServe HTTP endpoints in the plugin's own /x/plugins/<name>/ namespace (apps, local callers, and the handler behind public ingress).
Channelschannels/ingress.jsonDeclare public webhook and WebSocket routes that make the plugin a channel. The gateway verifies them and forwards to matching routes.
Appsapps/<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, /workspace/mcp.json for MCP servers) and the assistant picks it up automatically. No manifest, no install step, no peer dependency. A plugin is the way to ship those same servers with a versioned, installable unit.

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.

Before you write a single file

Ask before building. Six questions, in this order. Stop if the user is unclear on any of them.

  1. What job does the plugin do? One sentence, plain language. If you cannot write this, the plugin should not be built yet.
  2. Which surfaces does it ship? Pick from the surfaces table above. Most plugins ship one or two, not all of them. See references/plugins.md for the directory layout and manifest, and the surface-specific references for each surface's contract.
  3. Does it need credentials? An API key, OAuth token, or webhook secret is not a value that belongs in a .ts file. For LLM inference credentials, use getConfiguredProvider() from @vellumai/plugin-api to route through the workspace's stored credentials without handling plaintext. For other credential types (OAuth tokens, webhook secrets), store them via the credential vault and resolve at runtime with resolveCredential() from @vellumai/plugin-api, which returns the plaintext value scoped to the service named after your plugin (the install-directory basename). Call it from a hook, plugin tool, plugin route, a plugin skill TOOLS.json executor, or a companion script under skills/<skill>/{scripts,tools}/. A bash or skill-sandbox child inherits VELLUM_PLUGIN_NAME when exactly one plugin skill is active. A standalone bun invocation of a script under that layout also recovers the plugin name from its path. Catch CredentialResolutionError to degrade gracefully. Do not shell out to assistant credentials reveal.
  4. Does it keep state? A plugin is fully self-contained: durable state lives in its data/ directory (InitContext.pluginStorageDir), with schema created idempotently by the init hook, handles closed in shutdown, and per-conversation rows purged in conversation-deleted. A plugin never persists state in the assistant's database or elsewhere in the workspace. See "State is plugin-owned" in references/plugins.md.
  5. Where will the source live? A GitHub repo, ideally under the user's own namespace. The marketplace entry pins to a full commit SHA.
  6. Is the user writing TypeScript or compiling ahead? In-repo Bun/Node compile on assistant start is the default. If they want a different build, ask now.

You have an alignment problem if the user cannot answer questions 1 and 2. Push back and clarify before scaffolding. The most expensive waste of plugin-authoring time is building a plugin whose job is fuzzy.

Show full SKILL.md (500 more words)Show less

Scaffold the directory

Choose a kebab-case directory name. It becomes the install name. @scope/<name> is allowed; the loader strips the scope for the runtime plugin name. Duplicate names fail registration. See references/plugins.md for the full directory layout, manifest fields, and loader rules.

To exercise the plugin locally before pushing to the catalog, you have two options:

Option A: direct copy. Copy the directory into the workspace's plugins/ folder:

cp -R my-plugin $VELLUM_WORKSPACE_DIR/plugins/my-plugin

Option B: install from a GitHub URL (untrusted). If the plugin is already pushed to a public GitHub repo, install it directly without waiting for marketplace review:

assistant plugins install https://github.com/owner/my-plugin
assistant plugins install https://github.com/owner/repo/tree/my-branch/packages/my-plugin
assistant plugins install owner/repo --name my-plugin

A URL install bypasses the marketplace entirely: the tree is cloned verbatim (no adapter stub is overlaid) and the source is untrusted. The CLI prints a yellow warning naming the source. See references/distribution.md for the full details.

Verify before shipping

  1. Plugin directory copied into plugins/<name>/, assistant plugins list shows status ok (not error, not skipped).
  2. assistant plugins inspect <name> reports up-to-date and drift: none.
  3. Each surface the plugin ships exercised on a real code path — invoked, fired, loaded, or opened the way a user would reach it.
  4. Compiled files win: if you ship both .js and .ts for the same basename, the .js is loaded.

If a surface fails to load or fire, see references/plugins.md for loader rules and references/distribution.md for the CLI diagnostic commands.

Shipping to the catalog

See references/distribution.md for the full publishing walkthrough (push to GitHub, add a marketplace.json entry with a copy-pasteable template, and what the review checks), plus the manifest schema, CLI commands, and commit-pinning rules.

Once merged, users install by name: assistant plugins install my-plugin. The new plugin is picked up automatically.

SKILL COMPLETE WHEN

  • Job and surfaces locked in the alignment pass (questions 1 and 2 answered).
  • Directory matches the loader convention: one subdirectory (or declared file) per surface it ships (see the surfaces table), plus an optional src/ for internal modules.
  • package.json declares name, version, and a real peerDependencies["@vellumai/plugin-api"] range.
  • Any durable state lives in data/, created by init and cleaned up by shutdown / conversation-deleted.
  • Each surface has been exercised locally with a working example.
  • A marketplace.json entry exists with a full SHA in source.ref, and the Vellum team's review is in flight.

Reference files

  • references/plugins.md: Directory layout, manifest fields, and the full @vellumai/plugin-api export surface.
  • references/hooks.md: Every lifecycle hook with its context fields, the agent loop diagram, resolution order, and a hook anatomy example.
  • references/tools.md: Tool definition fields, the execute context, result shape, resolution order, and a tool anatomy example.
  • references/skills.md: Frontmatter reference, resolution order, and a skill anatomy example.
  • references/mcp.md: Root mcp.json declarations, transports, server ids, credentials, and risk defaults.
  • references/routes.md: The /x/plugins/<name>/ namespace, path mapping, handler signature, and a route anatomy example.
  • references/channels.md: channels/ingress.json, public /webhooks/plugins/<name>/ routes, guardian approval, verification, and inbound delivery.
  • references/apps.md: The Preact + TSX app structure, src/→dist/ compilation, the plugins~<name>~<app> id scheme, serving in the workspace panel, and an app anatomy example.
  • references/distribution.md: Marketplace catalog, CLI commands, drift and upgrades, the manifest schema, commit pinning, and adapters.

© vellum-ai, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 9 other files (references) in skills/plugin-builder of vellum-ai/vellum-assistant.

  • SKILL.md
  • references/apps.md
  • references/channels.md
  • references/distribution.md
  • references/hooks.md
  • references/mcp.md
  • references/plugins.md
  • references/routes.md
  • references/skills.md
  • references/tools.md

Open the folder on GitHubat commit c92ead1

Compare with similar skills

Plugin Builder next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Plugin Builder compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Plugin Builder this skillvellum-ai/vellum-assistant1.4k—~3.1kAutomated safety check: PassMIT
Scaffoldingdotnet/efcore15k—~165Automated safety check: PassMIT
Scaffold Elementremotion-dev/remotion62k—~202Automated safety check: PassCustom licence
Shipsimstudioai/sim30k—~4.1kAutomated safety check: PassApache-2.0
Builder Smoke Testmastra-ai/mastra29k—~11kAutomated safety check: NotesCustom licence
Ship Itvectorize-io/hindsight47k—~1.9kAutomated safety check: PassMIT

Similar skills

  • Scaffolding

    dotnet/efcore

    Official

    Implementation details for EF Core scaffolding (reverse engineering).

    15k GitHub stars~165 tokensUpdated today
    SecurityAuto-check passed
  • Scaffold Element

    remotion-dev/remotion

    Official

    Scaffold a new Remotion Element for development in the docs Remotion Studio.

    62k GitHub stars~202 tokensUpdated today
    Media & CreativeAuto-check passed
  • Ship

    simstudioai/sim

    Commit, push, and open a PR to staging in one shot — runs the cleanup pass and, when migrations changed, the db-migrate safety review first

    30k GitHub stars~4.1k tokensUpdated today
    DevelopmentAuto-check passed
  • Builder Smoke Test

    mastra-ai/mastra

    Smoke test the Agent Builder feature branch end-to-end against a hermetic project scaffolded by the skill (linked to the current worktree).

    29k GitHub stars~11k tokensUpdated today
    Testing & QAAuto-check: notes
  • Ship It

    vectorize-io/hindsight

    Take a PR from review to merged — run the repo's code-review skill on it in a loop (review, fix, re-review) until nothing is left to fix, applying ALL fixes on the PR branch, wait for CI green, then…

    47k GitHub stars~1.9k tokensUpdated today
    DevelopmentAuto-check passed
  • Ship Workflow

    garrytan/gstack

    Takes finished code to a pull request: merges the base branch, runs tests, reviews the diff, bumps VERSION, updates the CHANGELOG, commits, pushes and opens the PR.

    136k GitHub stars~20k tokensUpdated today
    DevelopmentAuto-check: notes

More from vellum-ai/vellum-assistant

All 108 skills in this repo
  • Vellum GitHub App Setup

    vellum-ai/vellum-assistant

    Create and configure a GitHub App so the assistant can push commits, open PRs, and comment under its own bot identity.

    1.4k GitHub stars~3.1k tokensUpdated today
    Auto-check passed
  • Discord App Setup

    vellum-ai/vellum-assistant

    Connect a Discord bot to the assistant via the Discord Gateway with guided application creation and intent configuration

    1.4k GitHub stars~4.2k tokensUpdated today
    Auto-check passed
  • Sentry App Setup

    vellum-ai/vellum-assistant

    Create and configure a Sentry internal integration so the assistant can manage issues, alerts, and releases under its own identity

    1.4k GitHub stars~1.3k tokensUpdated today
    Auto-check passed
  • Memory Corpus Ingest

    vellum-ai/vellum-assistant

    Ingest a large dataset into memory as a skimmed map. An agent skill from vellum-ai/vellum-assistant.

    1.4k GitHub stars~3k tokensUpdated today
    Auto-check: notes
  • Slack App Setup

    vellum-ai/vellum-assistant

    Connect a Slack app to the Vellum Assistant via Socket Mode.

    1.4k GitHub stars~2.5k tokensUpdated today
    Auto-check: warnings
  • Amazon

    vellum-ai/vellum-assistant

    Shop on Amazon and Amazon Fresh through your browser. An agent skill from vellum-ai/vellum-assistant.

    1.4k GitHub stars~1.2k tokensUpdated today
    Auto-check passed

Questions about Plugin Builder

What does Plugin Builder do?

A skill your agent uses 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. Plugin Builder is an agent skill from vellum-ai/vellum-assistant. 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.

When should I use Plugin Builder?

Plugin Builder fits situations like: the user wants to build; edit a Vellum plugin that bundles multiple surfaces (hooks; more) into one installable package.

How do I install Plugin Builder in Claude Code?

Run `npx skills add vellum-ai/vellum-assistant --skill plugin-builder -a claude-code`. Or copy the skill folder (skills/plugin-builder in vellum-ai/vellum-assistant) into .claude/skills/plugin-builder in your project. Claude Code loads it when a task matches its description.

How do I install Plugin Builder in Codex?

Run `npx skills add vellum-ai/vellum-assistant --skill plugin-builder -a codex`. Or copy the skill folder (skills/plugin-builder in vellum-ai/vellum-assistant) into .agents/skills/plugin-builder in your project. Codex loads it when a task matches its description.

Can I use Plugin Builder in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add vellum-ai/vellum-assistant --skill plugin-builder -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/plugin-builder, .gemini/skills/plugin-builder, .github/skills/plugin-builder and .opencode/skills/plugin-builder in your project.

What does Plugin Builder need to run?

SKILL.md names no scripts, command-line tools or credentials: Plugin Builder is instructions for the agent only. Compatibility (from SKILL.md): Designed for Vellum personal assistants.

Does Plugin Builder access the network?

SKILL.md names 1 domain. In commands or code: github.com; the agent is likely to contact it when it follows the instructions. This is read from the text; nothing was executed.

Is Plugin Builder safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Plugin Builder use?

Plugin Builder is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Plugin Builder use?

About 3.1k tokens (SKILL.md is roughly 12k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 41k tokens, read only when the agent opens those files.

What are the alternatives to Plugin Builder?

Skills that share tags, products or a category with Plugin Builder: Scaffolding (dotnet/efcore, 15k stars), Scaffold Element (remotion-dev/remotion, 62k stars), Ship (simstudioai/sim, 30k stars) and Builder Smoke Test (mastra-ai/mastra, 29k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Plugin Builder?

vellum-ai (a GitHub organization) maintains it in vellum-ai/vellum-assistant, which has 1,397 GitHub stars. The repository holds 108 skills in this directory. The repository was last updated on October 7, 2026.

Source: vellum-ai/vellum-assistant on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.