tyrn.json reference

tyrn.json sits at the root of a repository and lists the items it contains. It is JSON, schema 1.

Limits

The file is at most 256 KiB.
It lists 1 to 200 items.
Item ids must be unique within the file.
Paths are relative to the repository root, can’t contain .., and can’t point outside the repository.

Top level

Field	Type	Required	Notes
`schema`	number	Yes	Must be `1`.
`items`	array	Yes	The items, 1 to 200.
`publisher`	string	No	Up to 1024 bytes.

Item fields

Field	Type	Required	Notes
`kind`	string	Yes	`plugin`, `skill`, `connector`, `subagent` or `role`.
`id`	string	Yes	Unique id for the item.
`name`	string	Yes	Display name, not empty, up to 1024 bytes.
`path`	string	Yes	Where the item lives. See below.
`version`	string	No	Up to 1024 bytes.
`description`	string	No	Up to 4096 bytes.
`author`	string	No	Not empty, no control characters, up to 1024 bytes.
`homepage`	string	No	An `http` or `https` URL, up to 2048 bytes.
`icon`	string	No	Path to a `.png` file inside the repository. Up to 1 MiB.
`harnesses`	string array	No	Harness ids the item supports. Up to 64 entries. Each uses only ASCII letters, digits, `_`, `-` and `.`.
`surfaces`	string array	No	Plugin items only. What the plugin provides. Up to 16 entries. If left out, Tyrn works it out from the files.
`auth`	object	No	Connector items only. See below.

path by kind

plugin, skill, connector: a directory.
subagent: a .md file. It must list at least one harness in harnesses.
role: a .json file, up to 64 KiB. Its harness decides the item’s harness.

Role file

A role file is JSON with these fields.

Field	Type	Required
`harness`	string	Yes
`settings`	object of strings	No
`plugins`	string array	No
`subagents`	string array	No
`subagent_models`	object of strings	No

Each list or object holds up to 64 entries, and strings are up to 1024 bytes.

auth (connectors)

Field	Type	Notes
`type`	string	`none`, `env` or `oauth`.
`env`	array	For `env`. 1 to 16 fields.
`server`	string	For `oauth`. A server name from the connector’s `.mcp.json`.
`scopes`	string array	For `oauth`. Up to 32, no whitespace.
`client_id`	string	For `oauth`. Optional.

Each env field:

Field	Type	Required	Notes
`name`	string	Yes	Environment variable name. Listed once.
`label`	string	Yes	Shown in the form. Up to 128 bytes.
`help`	string	No	Up to 512 bytes.
`url`	string	No	`http` or `https` link to where you get the value. Up to 512 bytes.
`secret`	boolean	No	Default `true`.
`optional`	boolean	No	Default `false`.

Complete example

{
  "schema": 1,
  "publisher": "acme",
  "items": [
    {
      "kind": "plugin",
      "id": "acme-tools",
      "name": "Acme Tools",
      "version": "1.2.0",
      "description": "Skills and commands for Acme projects.",
      "path": "plugin",
      "icon": "icon.png",
      "author": "Acme",
      "homepage": "https://acme.example",
      "harnesses": ["claude_code", "codex"]
    },
    {
      "kind": "connector",
      "id": "acme-api",
      "name": "Acme API",
      "version": "1.0.0",
      "path": "connectors/acme",
      "auth": {
        "type": "env",
        "env": [
          {
            "name": "ACME_API_KEY",
            "label": "API key",
            "help": "Create a key in your Acme settings.",
            "url": "https://acme.example/settings/keys"
          }
        ]
      }
    },
    {
      "kind": "subagent",
      "id": "acme-reviewer",
      "name": "Acme Reviewer",
      "path": "subagents/reviewer.md",
      "harnesses": ["claude_code"]
    }
  ]
}

Next steps