Plugin manifest reference

Every plugin describes itself in a JSON file called plugin.json. This page lists every field Syntic Code reads from it, with types, defaults and how each one is used.

Where the manifest lives

Syntic Code looks in the plugin folder for, in order:

1. .syntic-plugin/plugin.json
2. plugin.json at the root

The first one found is used. If there is neither, but the folder has a SKILL.md at its root, the folder still loads as a plugin: its name is the folder’s name, its version is 0.0.0, and its only component is that skill.

Unknown fields

Fields the loader does not know are ignored, so a manifest written for a newer version still loads on an older one. The flip side is that a misspelled field ("command" instead of "commands") is silently ignored at load time. Run the validator to catch these.

Validate

syntic plugin validate ./my-plugin          # a folder or the manifest file itself
syntic plugin validate ./my-plugin --json   # machine-readable result

Errors make the command exit with code 1. Warnings do not.

Fields

Identity and metadata

Behaviour

Component paths

These say where the plugin’s components are. Each is optional; without it, the component’s default location is used when it exists.

outputStyles, mcpServers and lspServers also accept the spellings output_styles, mcp_servers and lsp_servers.

Path rules

• One path or several. Each field takes a string or an array of strings: "commands": "./cmds" or "commands": ["cmds/release.md", "cmds/hotfix.md"].
• Relative to the plugin folder. A leading ./ is fine.
• Must stay inside. A path containing .., or one that is absolute, is skipped at load time without a message. validate reports it as an error.
• Must exist. Paths that do not exist are skipped.
• Replaces the default. Naming a path for a component means its default location is no longer read for that component. To keep both, list both: "commands": ["commands", "extra-commands"].
• Markdown folders are flat. For agents and outputStyles, a folder contributes the .md files directly inside it. (Commands found through the standard commands/ layout may be nested; sub-folders become part of the name.)
• Skill folders need SKILL.md. In a folder of skills, only sub-folders that contain one count.
• Server files may be wrapped. mcpServers files may be { "mcpServers": { … } } or a bare map; lspServers files may be { "lspServers": { … } } or a bare map; hooks files may be { "hooks": { … } } or the bare event map. A file that does not parse is skipped.

monitors

"monitors": [
  { "name": "ci", "command": "${SYNTIC_PLUGIN_ROOT}/bin/watch-ci", "description": "CI status", "when": "launch" }
]

Entries missing name or command are skipped.

userConfig

A map from option key to its definition:

"userConfig": {
  "registry": { "type": "string", "default": "https://registry.example.com" },
  "token": { "type": "string", "required": true, "sensitive": true },
  "port": { "type": "number", "min": 1, "max": 65535 },
  "verbose": { "type": "boolean", "default": false },
  "include": { "type": "directory", "multiple": true }
}

Where values are stored

Using a value

Plugin variables

In text the model reads and in server settings, ${NAME} is replaced before use. In anything run by a shell, the variables are exported in front of the command instead, and the plugin’s bin/ is added to the front of PATH. Only these exact SYNTIC_ names are recognised.

A complete example

{
  "name": "release-helper",
  "version": "1.5.0",
  "description": "Release chores: version bumps, changelog, tags",
  "author": { "name": "Platform team", "email": "platform@example.com" },
  "homepage": "https://docs.example.com/release-helper",
  "repository": "https://github.com/acme/tools",
  "license": "MIT",
  "defaultEnabled": true,
  "dependencies": ["core"],
  "commands": ["commands", "extra-commands"],
  "mcpServers": "config/servers.json",
  "monitors": [
    { "name": "ci", "command": "${SYNTIC_PLUGIN_ROOT}/bin/watch-ci", "when": "skill:ship" }
  ],
  "userConfig": {
    "registry": { "type": "string", "default": "https://registry.example.com" },
    "token": { "type": "string", "required": true, "sensitive": true }
  }
}

Marketplace entries and the manifest

The marketplace entry that lists a plugin has its own fields (name, source, description, category, tags, strict). They describe the plugin in the catalog. What loads is always decided by the plugin’s own plugin.json. See the marketplace reference.

Related pages

• Plugin components
• Create a plugin
• Plugin commands