Connect capabilities from GitHub

A plugin is a directory in a GitHub repository that follows a simple layout. Connecting it makes everything inside Available. Cengrid reads the files only: it never runs repository scripts, hooks or package installs during import.

Before you start

You need to be an organisation administrator, and the organisation needs a working GitHub connection. All plugin repository access uses that one connection, for public and private repositories alike. Personal sign-ins, team connections and service credentials are never used for plugin imports.

1. Open Connections in the admin console and select Organisation scope.
2. Configure the GitHub definition with a token that can read the repositories you want to import, for example a fine-grained token from a service account limited to selected repositories. A read-only token is enough for plugins.
3. Enable the connection.

If the connection is missing or has no usable credential, the Plugins page opens Connections with the GitHub configuration ready to edit. Details are on GitHub connection.

Connect a plugin

1. Open Plugins and choose to connect a repository.
2. Enter the repository as a URL or owner/repository.
3. Optionally set a branch, tag or commit, and a plugin directory. Leave the directory empty if the plugin sits at the repository root.
4. Connect. Cengrid fetches and validates the files. An error rejects the connection with a message naming the file. Warnings, such as unknown settings or unsupported hooks, are shown on the plugin.
5. Go to the capability page for each kind you want, open Available, and Add the items to the organisation or a team.

A repository that holds several plugins can have one connection per directory, or publish a marketplace and be linked once.

Plugin layout

• Directorymy-plugin/

  • plugin.json
  • connections.json
  • mcp.json
  • Directoryinstructions/

    • Directoryrelease-practices/

      • INSTRUCTIONS.md
  • Directoryskills/

    • Directoryreview/

      • SKILL.md
      • references/style.md
  • Directoryagents/

    • Directorydata-analyst/

      • AGENT.md
      • tools.json
      • test_cases.json
  • Directoryenvironments/

    • Directorytoolchain/

      • environment.json
      • mise.toml
      • setup.sh
  • Directoryplaybooks/

    • Directorysoftware-development/

      • PLAYBOOK.md
  • Directoryapps/

    • Directoryreports/

      • app.json
      • Dockerfile
      • server.js

Only the manifest is required. This is a complete, valid plugin:

plugin.json

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

Cengrid also reads .codex-plugin/plugin.json and .claude-plugin/plugin.json, custom component paths, and the legacy .mcp.json. A root plugin.json takes precedence. Field-by-field detail is in plugin and marketplace files.

What is not supported

Plugin hooks and commands are reported as unsupported. HTTP MCP servers are supported; stdio and SSE transports, custom MCP headers and templated endpoints are shown as unavailable, or reject the plugin if the URL cannot be parsed, rather than being silently altered. Skill settings allowed-tools, context, agent, hooks and disable-model-invocation, and agent settings tools, disallowedTools, permissionMode, hooks, mcpServers and isolation, mark the item unavailable.

Link a marketplace

A marketplace is a repository with a marketplace.json that lists up to 100 plugins. Link it once and every plugin Cengrid can load becomes a connected plugin.

1. Open Plugins → Link a marketplace.
2. Enter the repository (URL or owner/repository), an optional branch, tag or commit, and the marketplace directory that holds marketplace.json. Leave the directory empty if the file is at the repository root.
3. Link. Each listed plugin appears with its own items under Available. Nothing is added to a scope until you choose it.

marketplace.json

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

Each entry’s source decides where its files come from:

source	Plugin files
"./plugins/x"	A directory relative to the marketplace directory (the repository root if you left that empty), read at the marketplace’s commit. The ./ prefix is required.
{ "source": "github", "repo": "owner/repo", "ref"?, "sha"? } or { "source": "url", "url": "https://github.com/owner/repo" }	The root of another GitHub repository.
{ "source": "git-subdir", "url": "owner/repo", "path": "tools/x", "ref"?, "sha"? }	A directory in another GitHub repository.

sha must be a full 40-character lowercase commit SHA and takes precedence over ref. Entries from npm, archive or command sources, from hosts other than github.com, or with an invalid path or sha are listed as Not available with the reason.

Marketplace plugins are managed by their marketplace: use the marketplace’s own Re-sync and Remove. The organisation’s GitHub connection reads every repository a marketplace points at, so link only marketplaces you trust.

Keep plugins up to date

Cengrid fetches GitHub only when an administrator asks. Choose Re-sync on a plugin or marketplace to pull changes.

• Definitions the plugin owns are updated in every scope that added them, including disabled ones, and on/off overrides are preserved.
• New files appear in Available. Deleted files remove the definitions they owned. A rename is a removal plus a new Available item.
• Invalid files or model settings reject the whole sync before any saved snapshot changes.
• Remove plugin disconnects the repository and removes every definition, bundle and app copy it owns across scopes.

Try the examples

The product repository ships three working examples under examples/. See capability examples for step-by-step walkthroughs.