Skip to content

Agent Plugins

Jump to bottom
Vinh Nguyen edited this page Aug 7, 2026 · 1 revision

Agent Plugins

VT Code supports the Agent Plugins 1.0.0 portable package format. A plugin is a directory containing a root plugin.json manifest, optional skills/*/SKILL.md Agent Skills, and optional mcp.json MCP server configuration. Install a plugin and its skills and MCP servers become available to VT Code immediately.

See the Agent Plugins specification for the portable package contract.

What a plugin gives you

my-plugin/
├── plugin.json              # required: $schema + name
├── skills/
│   └── my-skill/
│       └── SKILL.md         # Agent Skill (name must match its folder)
└── mcp.json                 # optional MCP servers
  • Skills under skills/*/SKILL.md are discovered from <workspace>/.agents/plugins and appear alongside your regular skills.
  • MCP servers declared in mcp.json are exposed as <plugin>.<server> providers and connect automatically at session startup. stdio and streamable-http transports are supported; legacy sse is skipped.

Commands

vtcode plugins add https://github.com/example/my-plugin   # install (git URL or local dir) into ~/.agents/plugins
vtcode plugins list                                        # list installed plugins
vtcode plugins info my-plugin                              # plugin details
vtcode plugins validate ./my-plugin                        # validate without installing
vtcode plugins remove my-plugin                            # uninstall

plugins add clones git URLs with git clone --depth=1 and requires local directories to contain a valid plugin.json.

Manifest requirements

plugin.json requires $schema (the Agent Plugins 1.0.0 schema) and name (1-64 chars of a-z, 0-9, -, ., starting and ending alphanumeric, no -- or ..). Unknown top-level fields are non-fatal and reported.

Configuration

Control plugins via the tools.plugins section in vtcode.toml:

[tools.plugins]
enabled = true            # toggle the plugin runtime
default_trust = "sandbox" # sandbox | trusted | untrusted
allow = ["my-plugin"]     # optional allow-list
deny = []                 # optional block-list
auto_reload = true        # hot-reload manifest polling

Security

  • ./-prefixed command and cwd paths must resolve inside the plugin root; escaping paths are rejected.
  • For stdio servers, VT Code injects PLUGIN_ROOT and PLUGIN_DATA environment variables and expands ${PLUGIN_ROOT} / ${PLUGIN_DATA} placeholders in args, env, and cwd. PLUGIN_DATA defaults to <plugin-root>/data and is created before the subprocess launches.

Related

Clone this wiki locally