Plugin Formats

​

Formats

​

One package for Enconvo, Codex and Claude Code

npx -p @enconvo/api enconvo plugin create notes --template skills   # a skill
npx -p @enconvo/api enconvo plugin create notes --template mcp      # an MCP server

notes/
├── plugin.json                  # portable manifest: name, version, description
├── .codex-plugin/plugin.json    # the Codex listing (interface)
├── .claude-plugin/plugin.json   # the Claude Code manifest
├── skills/hello/
│   ├── SKILL.md
│   └── agents/openai.yaml       # the skill's name and example prompt
├── mcp.json                     # MCP servers for Codex and Enconvo (mcp template)
├── .mcp.json                    # the same servers for Claude Code (mcp template)
├── mcp/server.mjs               # a dependency-free MCP server (mcp template)
└── assets/icon.png

​

How Enconvo reads the manifests

​

Name, title and description

​

Listing (interface)

{
  "name": "deploy-tools",
  "version": "1.0.0",
  "icon": "./logo.png",
  "documentationUrl": "https://example.com/docs",
  "supportUrl": "https://example.com/support",
  "privacyPolicyUrl": "https://example.com/privacy",
  "termsOfServiceUrl": "https://example.com/terms"
}

{
  "name": "notes",
  "version": "1.2.0",
  "description": "Search and summarize your notes.",
  "author": { "name": "Ada Lovelace" },
  "interface": {
    "displayName": "Notes",
    "shortDescription": "Search your notes",
    "developerName": "Ada Lovelace",
    "category": "Productivity",
    "defaultPrompt": ["Find my notes about the Q3 launch"],
    "websiteURL": "https://example.com/notes",
    "privacyPolicyURL": "https://example.com/privacy",
    "brandColor": "#0A84FF",
    "logo": "./assets/icon.png"
  }
}

"extensions": {
  "com.openai": {
    "publication": {
      "translations": {
        "fr-FR": { "subtitle": "Cherchez vos notes", "description": "Cherchez vos notes depuis le chat." }
      }
    }
  }
}

​

Onboarding skill

​

MCP servers

1. mcpServers in the manifest: the servers themselves, or a path to a file of them. In a portable plugin, only .claude-plugin/plugin.json’s counts.
2. mcp.json at the root (the portable format).
3. .mcp.json at the root (Claude Code).
4. mcpServers in package.json.

{
  "mcpServers": {
    "notes": { "type": "stdio", "command": "node", "args": ["./mcp/server.mjs"], "cwd": "./" },
    "notes-cloud": { "type": "streamable-http", "url": "https://example.com/mcp" }
  }
}

• Transports: stdio, http (also written streamable-http or streamable_http) and sse. Servers of other types, such as ws, are skipped.
• Claude Code reads strictly: it drops a server with a url but no type, an unknown type, or a field of the wrong shape, such as an empty command or a timeout that isn’t a positive whole number. Its tools is a list of {"name", "permission_policy"}, while Codex’s is an object of tool settings by tool name, so a server with either form fails in the other app: give each its own MCP file, or leave tools out. enconvo plugin validate reports all of these (see MCP servers and apps).
• Working folder: a relative cwd starts at the plugin’s folder.
• Remote servers: use https:// (or wss://) for anything but this computer, and never commit a token or key in headers: everyone who installs the plugin can read it. Reference a sensitive setting or an environment variable instead, such as "Authorization": "Bearer ${user_config.api_token}". enconvo plugin validate warns about both, as claude plugin validate does (see MCP servers and apps).
• Variables in command, args, env, cwd, url and headers:

​

Signing in to a remote server

{
  "mcpServers": {
    "tracker": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "client_id": "your-app-id",
        "callback_port": 3118,
        "callback_url": "http://127.0.0.1:3118/callback"
      }
    }
  }
}

• Claude Code writes clientId and callbackPort, and the sign-in comes back to http://localhost:<callbackPort>/callback.
• Codex writes client_id, callback_port, callback_url and, for a confidential app, client_secret.
• Register the app’s redirect as written: Enconvo listens on that port while someone signs in, then finishes the sign-in itself. If another app is using the port, the sign-in asks the person to close it and try again.
• The redirect has to be an http address on the same computer (127.0.0.1, localhost or [::1]).
• While the app’s fields still hold placeholders such as <CLIENT_ID> or an unset ${VAR}, Enconvo ignores the app and signs in the usual way.

• oauth_resource (Codex, next to url) is the resource the token is for. Enconvo sends it to the authorization server exactly as written, in the sign-in and in every renewal, so a server that compares it as a string (https://mcp.notion.com without a trailing slash) accepts the token. It has to be on the server’s own origin; otherwise Enconvo signs in without it.
• oauth.authServerMetadataUrl (Claude Code) is where the authorization server’s metadata is, for a server that doesn’t publish it. Enconvo reads it instead of looking at the server’s well-known addresses, and shows Sign in for the server even when they answer nothing. It has to use https://; Enconvo also reads http:// from localhost while you test, which Claude Code doesn’t. When the address can’t be read, Enconvo looks the usual way.

​

Which tools run, and when Enconvo asks

{
  "mcpServers": {
    "tracker": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "disabled_tools": ["delete_project"],
      "default_tools_approval_mode": "writes",
      "tools": {
        "search": { "approval_mode": "auto" },
        "send_invoice": { "approval_mode": "prompt" }
      }
    }
  }
}

• enabled_tools offers only the tools it lists; disabled_tools hides the ones it lists.
• default_tools_approval_mode sets how all the server’s tools are approved, and tools.<tool>.approval_mode sets it for one tool:

​

Skills

---
name: summarize-notes
description: Summarizes a set of notes into key points. Use when the user asks for a summary of their notes.
---

Instructions the agent follows when it uses the skill.

interface:
  display_name: "Summarize Notes"
  short_description: "Key points from your notes"
  default_prompt: "Summarize my notes from this week"
policy:
  allow_implicit_invocation: false   # only when the user picks it

---
name: summarize-notes
description: Summarizes the user's notes for a date range, grouped by project, with open questions and decisions listed separately.
metadata:
  short-description: Key points from your notes
---

dependencies:
  tools:
    - type: "mcp"
      value: "linear"
      description: "Linear MCP server"
      transport: "streamable_http"   # the default; or "stdio" with a command
      url: "https://mcp.linear.app/mcp"

---
name: triage-crash
description: Reads a crash log and names the likely cause.
when_to_use: Use when the user pastes a stack trace or a crash report.
user-invocable: false
---

• when_to_use is added to the description the agent sees (description - when_to_use), and skill search matches it too.
• user-invocable: false keeps the skill out of the / and $ menus and the SmartBar’s skill search, for skills that only make sense when the agent picks them. The agent still sees and uses it.

Run `python3 ${CLAUDE_SKILL_DIR}/scripts/report.py --region ${user_config.region}`.

​

Claude Code commands

{
  "commands": {
    "status": { "source": "./commands/status.md", "description": "Show the deployment status", "argumentHint": "[env]" },
    "about": { "content": "Describe what this plugin does.", "description": "Describe this plugin" }
  }
}

---
description: Create a git commit
argument-hint: [message]
---

Current status: !`git status`

Commit the staged changes with the message $ARGUMENTS.

• ${CLAUDE_PLUGIN_ROOT} and ${CLAUDE_PLUGIN_DATA} become the plugin’s installed folder and its data folder, and ${user_config.KEY} the plugin’s setting, as in skills.
• $ARGUMENTS, $1 and named arguments stand for what the person wrote with the command, and the agent runs !`command` lines and ```! blocks with its shell tool before it follows the rest.
• disable-model-invocation: true (or the older hide-from-slash-command-tool: "true") makes it a skill only people start.
• user-invocable: false keeps it out of the / and $ menus, and when_to_use is added to what the agent sees, as in skills.
• allowed-tools and model are ignored: the agent keeps its usual tools, model and approvals.

​

Agents

---
name: code-reviewer
description: Reviews a diff for bugs. Use after editing code.
tools: Read, Grep, Glob
model: sonnet
---

Review the changes for bugs. Read ${CLAUDE_PLUGIN_ROOT}/checklist.md first.

• description tells the agent when to use the helper. <example> blocks are left out of what it sees.
• A tools list with only reading tools (Read, Grep, Glob, WebFetch, …), or permissionMode: plan, makes the helper read-only. Other tool lists limit what it may call.
• model is used when the chat’s model provider has a matching model, and the helper otherwise runs on the chat’s model.
• ${CLAUDE_PLUGIN_ROOT} and ${CLAUDE_PLUGIN_DATA} become the plugin’s installed folder and its data folder.

​

Hooks

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "./scripts/guard.sh", "timeout": 10 }] }
    ],
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/session-start.mjs\"" }] }
    ]
  }
}

• Matchers: a tool event’s matcher is a regular expression tested against the Enconvo tool’s name, title and command. A SessionStart matcher that doesn’t match startup never fires, since Enconvo only starts new chats.
• Commands: a command that starts with ./ runs the file in your plugin. Each command gets PLUGIN_ROOT and PLUGIN_DATA (and the CLAUDE_PLUGIN_ROOT and CLAUDE_PLUGIN_DATA names) in its environment, the plugin’s settings as CLAUDE_PLUGIN_OPTION_<KEY> (see Settings), and the event as JSON on stdin. A hook that runs in a chat with a working folder starts there and gets it as CLAUDE_PROJECT_DIR.
• Timeouts: timeout is in seconds, 60 by default and at most 600. A hook marked async starts and isn’t waited for.
• Skipped: other events (such as PostToolBatch or PreCompact), hooks whose type isn’t command, hooks with an if permission rule, and shell commands that name ${user_config.KEY} don’t run in Enconvo. The preview and the plugin’s page list them.

​

Settings

{
  "name": "my-database",
  "userConfig": {
    "region": { "type": "string", "title": "Region", "description": "Where your database runs", "options": ["us-east1", "europe-west1"], "default": "us-east1" },
    "password": { "type": "string", "title": "Password", "description": "Your database password", "sensitive": true, "required": true }
  },
  "mcpServers": {
    "db": {
      "command": "npx",
      "args": ["-y", "my-database-mcp", "--region", "${user_config.region}"],
      "env": { "DB_PASSWORD": "${user_config.password}" }
    }
  }
}

• Types: string becomes a text field, or a password field when sensitive; a string with options becomes a dropdown. number, boolean, file and directory keep their types, and required, default and multiple carry over.
• In MCP servers: ${user_config.KEY} in a server’s command, args, env, cwd, url or headers becomes the setting’s value. A setting with several values is joined with commas, or, when it’s the whole argument, becomes one argument per value.
• Sensitive settings are filled in only as the server starts, so they never appear in Enconvo’s saved server settings.
• Missing settings: a server that needs a required setting you haven’t filled in doesn’t start, and says which setting to fill in. An optional setting left empty becomes an empty value.
• Changes: saving a setting on the plugin’s page restarts the servers that use it, with the new value.
• Checks: Claude Code doesn’t load a plugin with a setting outside its rules, such as one without a title and description, or a ${user_config.KEY} in a server for a key no setting declares. Enconvo is more lenient, so run enconvo plugin validate to catch them before you share the plugin (see Claude Code settings and channels).
• In skills and commands: ${user_config.KEY} in a skill’s or command’s text becomes the setting’s value when the agent loads it (see Skills). A sensitive setting stays out of the conversation.
• In hooks: each setting is in a hook’s environment as CLAUDE_PLUGIN_OPTION_<KEY>, the key in capitals (api_token becomes CLAUDE_PLUGIN_OPTION_API_TOKEN), with the saved value or the default. true/false and numbers are written as text, and several values are joined with commas. ${user_config.KEY} works in a hook’s args, but not in a shell command, where a value could run as code: as in Claude Code, such a hook doesn’t run.

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/report.mjs", "--region=${user_config.region}"] }] }
    ]
  }
}

​

Channel settings

{
  "name": "chat-bridge",
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": { "BOT_TOKEN": "${user_config.bot_token}" }
    }
  },
  "channels": [
    {
      "server": "telegram",
      "displayName": "Telegram",
      "userConfig": {
        "bot_token": { "type": "string", "title": "Bot token", "description": "Telegram bot token", "sensitive": true, "required": true }
      }
    }
  ]
}

​

What Enconvo doesn’t load

​

Check a package

npx -p @enconvo/api enconvo plugin validate            # Enconvo, Codex and Claude Code rules
npx -p @enconvo/api enconvo plugin validate --openai   # also OpenAI's portal rules
npx -p @enconvo/api enconvo plugin scan                # starts the MCP servers and checks their tools