Create a Vibe Plugin

A plugin is a directory containing a plugin.json manifest (Agent Plugins 1.0 schema) plus optional component directories and config files. Vibe discovers plugins under .vibe/plugins/ (project scope, requires trusted folder) and ~/.vibe/plugins/ (user global).

Plugin discovery locations

Each subdirectory under a plugins root is one plugin package. The first match wins: project plugins take precedence over user plugins with the same name.

Plugin directory structure

my-plugin/
  plugin.json                 # required — Agent Plugins 1.0 manifest
  mcp.json                    # optional — MCP server definitions
  libraries.json              # optional — Node/Python library dependencies
  connectors.json             # optional — managed connector requirements
  skills/                     # optional — one subdirectory per skill
    my-skill/
      SKILL.md
  ai.mistral.vibe/            # optional — Vibe-specific extensions
    hooks.toml                # Vibe extension only
    knowledge/                # one subdirectory per knowledge folder
      topic-name/
        KNOWLEDGE.md
    agents/                   # one .toml per subagent
      researcher.toml
    INSTRUCTIONS.md           # optional plugin-wide instructions (not loaded)

Step 1 — plugin.json (required)

The manifest is a JSON file with $schema and name as required fields.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "What this plugin provides.",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/my-plugin",
  "repository": "https://github.com/example/my-plugin",
  "license": "MIT",
  "keywords": ["productivity", "finance"],
  "extensions": {}
}

Rules:

• name must match ^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$ (1-64 chars), no -- or ...
• $schema must be exactly https://agent-plugins.org/schemas/1.0.0/plugin.schema.json. Any other schema URL produces a fatal plugin.schema.version_unsupported error.
• All fields other than those listed above are rejected (extra="forbid").

Step 2 — Vibe extension (optional)

To use Vibe-specific components (hooks, knowledge, agents, libraries, connectors), add an ai.mistral.vibe extension to plugin.json:

{
  "extensions": {
    "ai.mistral.vibe": {
      "schemaVersion": 1,
      "toolNamespace": "myPlugin",
      "toolOverrides": {
        "lookup": {
          "name": "search",
          "exposure": "direct_and_programmatic"
        }
      }
    }
  }
}

Without this extension, Vibe only loads plugin.json, skills/, and mcp.json. The toolNamespace defaults to a TypeScript identifier derived from the plugin name. It must not be one of the reserved namespaces: file_system, self, process, agent, vibe.

vibe is reserved for built-in plugins shipped with the CLI; user plugins must choose a different namespace.

toolOverrides rename or restrict tool exposure. Each key matches a discovered tool name from MCP servers or connectors. exposure is one of programmatic, direct, or direct_and_programmatic.

Step 3 — Skills (optional)

Place skills under skills/ — one subdirectory per skill, each containing a SKILL.md. The skill name in SKILL.md frontmatter must match the directory name.

skills/
  format-reports/
    SKILL.md

Skills follow the standard SKILL.md format with YAML frontmatter (name, description, user-invocable, allowed-tools). Plugin skills are namespaced as <namespace>:<skill-name> at runtime.

Step 4 — MCP servers (optional)

Define MCP servers in mcp.json. Three transport types are supported:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "lookup": {
      "type": "stdio",
      "command": "node",
      "args": ["${PLUGIN_ROOT}/server/index.js"],
      "env": {
        "DEBUG": "true"
      },
      "cwd": "."
    },
    "remote-api": {
      "type": "streamable-http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "X-Custom-Header": "value"
      }
    }
  }
}

Rules:

• command, args, and env values support ${PLUGIN_ROOT} and ${PLUGIN_DATA} variable expansion.
• PLUGIN_ROOT and PLUGIN_DATA are also injected automatically into env; do not set them yourself (rejected with an error).
• env variable names PLUGIN_ROOT and PLUGIN_DATA are reserved.
• cwd of . means the plugin root.
• streamable-http servers support static headers only; use OAuth at the Vibe config level for authenticated remote servers.
• sse transport is detected but not supported — it produces a diagnostic.
• The command for stdio servers is resolved relative to the plugin root when it is a bare filename; absolute paths are used as-is.

Step 5 — Hooks (optional, Vibe extension only)

Place hooks in ai.mistral.vibe/hooks.toml. Format is identical to the Vibe hooks.toml format, but hooks run in the plugin root directory with PLUGIN_ROOT and PLUGIN_DATA in the environment.

[[hooks]]
name = "guard-lookup"
type = "pre_tool"
match = "myPlugin.lookup"
command = "python guard.py"
strict = true

[[hooks]]
name = "post-agent-lint"
type = "post_agent"
command = "eslint --quiet ."

Limits:

• Maximum 128 hooks per plugin.
• File size limit: 64 KB.
• Hook names must be unique within the plugin. Runtime names are prefixed as <plugin-name>:<hook-name>.

Step 6 — Knowledge (optional, Vibe extension only)

Place knowledge folders under ai.mistral.vibe/knowledge/. Each folder contains a KNOWLEDGE.md with YAML frontmatter:

ai.mistral.vibe/
  knowledge/
    accounting-policy/
      KNOWLEDGE.md
      reference.md

KNOWLEDGE.md frontmatter:

---
name: accounting-policy
description: How revenue is recognized and reported.
display_name: Accounting Policy
icon: book
---

Rules:

• name must match the directory name (^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$).
• description is 5-300 characters.
• Maximum 100 knowledge folders per plugin.
• KNOWLEDGE.md entrypoint limit: 256 KB.
• No symbolic links inside knowledge directories.
• Knowledge is namespaced as <namespace>:<name>.

Step 7 — Agents (optional, Vibe extension only)

Place subagent definitions under ai.mistral.vibe/agents/. Each .toml file defines one subagent:

ai.mistral.vibe/
  agents/
    researcher.toml

researcher.toml:

schemaVersion = 1
agentType = "subagent"
displayName = "Researcher"
description = "Searches the knowledge base and summarizes findings."
safety = "safe"
activeModel = "mistral-medium-3.5"
instructions = "You are a research assistant."

enabledTools = ["read_file", "grep"]
disabledTools = ["bash"]

[tools.bash]
permission = "never"
allowlist = ["ls"]
denylist = ["rm"]

Rules:

• schemaVersion must be 1.
• agentType must be "subagent" (the only supported type).
• Filename must be lowercase kebab-case (^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$).
• safety is one of "safe", "neutral", "destructive", "yolo".
• Maximum 128 agents per plugin, 64 KB per file.
• Tool lists cannot contain duplicates or empty names.
• Agent names are namespaced as <namespace>:<filename-stem>.

Step 8 — Libraries (optional, Vibe extension only)

Declare Node and Python library dependencies in libraries.json:

{
  "schemaVersion": 1,
  "node": {
    "@productivity/finance": "./node/finance",
    "lodash": "./node/lodash"
  },
  "python": {
    "vibe_finance": "./python/vibe_finance",
    "utils": "./python/utils.py"
  }
}

Rules:

• Node aliases must match ^(?:@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*$ (max 214 chars).
• Python aliases must match ^[A-Za-z_][A-Za-z0-9_]*$ (max 128 chars).
• Source paths are relative to the plugin root, using forward slashes only. No .. or absolute paths.
• Python library sources can be a directory (package) or a single .py file.
• Node library sources must be directories.
• No symbolic links inside library directories.
• Library aliases that collide across plugins are all dropped.
• Maximum 128 entries per language.

Step 9 — Connectors (optional, Vibe extension only)

Declare required managed connectors in connectors.json:

{
  "schemaVersion": 1,
  "connectors": [
    {
      "id": "github",
      "tools": ["create_issue", "list_issues"]
    },
    {
      "id": "linear",
      "tools": ["create_issue"]
    }
  ]
}

Rules:

• Connector IDs must be unique within the plugin.
• Tool names per connector must be unique, 1-256 characters.
• Maximum 128 connector requirements.
• A connector requirement is a declaration: it appears whether or not the account has the connector. Availability is reported as a diagnostic.

Diagnostic codes

When a plugin fails to load or has issues, Vibe emits typed diagnostics. The most common ones:

Fatal diagnostics drop the entire plugin. Non-fatal diagnostics drop only the offending component; the rest of the plugin survives.

Compatibility with other plugin formats

Vibe also detects and adapts plugins authored for other agents:

If markers for more than one format are present, the plugin is rejected as ambiguous. Native Agent Plugins 1.0 (a valid plugin.json with the correct $schema) always takes precedence.

When creating a new plugin, always use the native Agent Plugins 1.0 format.

Workflow

1. Determine the plugin name, scope (project vs user global), and which components the user needs.
2. Create the directory at .vibe/plugins/<name>/ (project) or ~/.vibe/plugins/<name>/ (user).
3. Write plugin.json with the required $schema and name fields.
4. Add the ai.mistral.vibe extension to plugin.json if any Vibe-specific components (hooks, knowledge, agents, libraries, connectors) are needed.
5. Add component directories and files per the instructions above.
6. Tell the user to run /reload to pick up the new plugin without restarting.