Plugin and marketplace files

Cengrid reads plugin files as data. It never runs scripts, hooks or package installs during import. See Connect capabilities from GitHub for how to connect one.

Files at a glance

Path	Kind	Required	Reference
`plugin.json`	Manifest	Yes	Below
`skills/<name>/SKILL.md`	Skill	No	Skills
`instructions/<name>/INSTRUCTIONS.md`	Instruction	No	Instructions
`agents/<name>/AGENT.md`	Agent	No	Agents
`mcp.json`	MCP servers	No	MCP servers
`connections.json`	API connection templates	No	Connections
`environments/<key>/environment.json`	Environment	No	Environments
`apps/<name>/app.json`	App	No	Apps
`playbooks/<name>/PLAYBOOK.md`	Playbook	No	Playbooks

plugin.json

A minimal manifest:

{
  "name": "team-toolkit",
  "description": "Shared team capabilities",
  "version": "1.0.0"
}

Field	Meaning
`name`	The plugin’s name.
`description`	Up to 1,000 characters.
`version`	A string, truncated to 80 characters.
`interface.displayName`	Optional display name, as in the static app example.
`skills`, `agents`, `instructions`, `playbooks`, `apps`	Optional relative directory, or array of directories, replacing the default `skills/`, `agents/`, `instructions/`, `playbooks/` and `apps/`. When `apps` is declared, an invalid app is an error rather than a warning.
`mcpServers`	A relative file path, an array of paths, or an inline object of servers. Defaults to `mcp.json`, then `.mcp.json`.
`connections`	A relative file path, an array of paths, or an inline definition map. Defaults to `connections.json`.

A declared component path that does not exist is reported as an error. The importer also reads .codex-plugin/plugin.json and .claude-plugin/plugin.json. A root plugin.json takes precedence. The environments/ path is fixed and cannot be changed.

Imported files that are not claimed by a component, such as plugin.json, mcp.json, connections.json, hooks and commands, are never turned into skill assets. .env files are never imported.

marketplace.json

{
  "name": "example-marketplace",
  "description": "Optional description",
  "plugins": [
    {
      "name": "release-habits",
      "source": "./plugins/release-habits",
      "description": "Draft release notes from merged changes",
      "category": "Productivity"
    }
  ]
}

Field	Meaning
`name`	Required. Letters, digits, dots, underscores and hyphens, up to 128 characters, starting with a letter or digit.
`description`	Optional, up to 1,000 characters.
`plugins`	Required array of up to 100 entries.
Entry `name`	Letters, digits, dots, underscores and hyphens. A plugin’s identity is the marketplace plus this name. A repeated name keeps only the first.
Entry `source`	Where the plugin’s files come from. See the table in connect capabilities.
Entry `description`	Up to 1,000 characters.
Entry `category`	Up to 80 characters.

If an entry’s directory has a manifest, it is read exactly like a standalone plugin and the component fields on the entry are ignored. If it has none, the entry itself is the manifest, so its description, skills, agents, instructions, connections, mcpServers and apps apply. That lets several entries share "source": "./" and each expose a different list.

Re-sync reads the file again. A plugin is removed, with everything it added, only when its entry disappears. A file that lists no plugins is refused while plugins are connected, so an accidental empty file cannot disconnect everything.