Marketplace setup file (catalex.yaml)

The CatalEx Marketplace imports a GitHub repo as one or more agents. An optional catalex.yaml file at the repo root sets each agent's name, picture, AI tool and starting settings. This page is for repo authors; to import an agent, see the Marketplace page.

Shortest working path

1. Make the repo public on GitHub. Put the agent's instructions in AGENTS.md, CLAUDE.md or SKILL.md at the repo root.
2. Add a README.md at the root that says what the agent does.
3. Optional: add catalex.yaml at the root. Without it, the repo imports as one agent that uses the whole repo as its folder and the importer's default settings.
4. In CatalEx, choose Marketplace, then Add a repo, paste https://github.com/OWNER/REPO (your GitHub user or organization and the repo name) and choose Import. Confirm the import. The agent appears on the Agents page. With the CLI, run catalex marketplace add https://github.com/OWNER/REPO.
5. If your listing shows the warning icon (Setup has some issues), choose it. It lists what CatalEx replaced with a default. Fix catalex.yaml, push, and the next daily refresh picks up the fix. With the CLI, catalex marketplace issues OWNER/REPO prints the same list.

Repo layout

my-repo/
  README.md              what the repo does, for people
  catalex.yaml           optional setup file
  AGENTS.md              instructions of the root agent
  assets/manager.png     optional agent picture (PNG or JPEG, up to 1 MiB)
  twin-manager/          one folder per agent
    AGENTS.md            instructions (or CLAUDE.md, or SKILL.md)
    .mcp.json            the agent's own tool servers

• Each agent has one folder with its instructions file in it. List several agents in catalex.yaml; each names its own folder. Agents may share a folder.
• Put an agent's tool servers in that folder's .mcp.json (the mcpServers object). catalex.yaml only chooses among them.
• CatalEx imports the complete repo, so instructions can refer to any file in it. Keep the repo, with its history, under 500 MiB; a larger repo is refused.

Examples

A minimal file declares one agent:

version: 1
agents:
  - name: Support Helper

A multi-agent file gives each agent its own folder and settings:

version: 1
agents:
  - name: Twin Manager
    description: Builds your brain from your notes
    folder: twin-manager
    picture: assets/manager.png
    provider: claude
    model: haiku
    effort: low
    isolation: folder
    tools:
      terminal_access: off
      sandbox: on
      command_internet: off
      approval_mode: manual
      mcp_servers: [calendar]
      tools_off: ["calendar:delete_event"]
    behavior:
      tone: friendly
      engagement_frequency: low
  - name: Reply Writer
    folder: reply-writer
    provider: codex

Field reference

Every setting except version and name is optional. A missing or empty setting means the importer's computer decides. Values are case-sensitive and compared as text, so an unquoted on or off works. Settings are starting values: the person can change them after the import, and a later update never resets those changes.

Setting	Values	Example
version	1. Required.	version: 1
agents	A list of up to 10 agents.	agents: then - name: ...
name	Required, 1 to 60 characters. A repeated name gets a number added.	name: Twin Manager
description	Up to 200 characters.	description: Builds your brain
folder	Path of the agent's folder inside the repo. Default . (the repo root).	folder: twin-manager
picture	Path of a PNG or JPEG of at most 1 MiB inside the repo.	picture: assets/manager.png
provider	claude or codex. A preference: a computer without it uses the one it has.	provider: codex
model	1 to 100 characters from letters, digits and . _ : -. If the AI tool on the computer does not offer it, that tool's default is used.	model: haiku
effort	low, medium, high, xhigh or max.	effort: low
isolation	folder or none. Applies to Claude only.	isolation: folder
tools.terminal_access	inherit, off or on.	terminal_access: off
tools.sandbox	on or off.	sandbox: on
tools.command_internet	on or off.	command_internet: off
tools.approval_mode	inherit, manual or deny. Never none or automatic: only the person may turn approvals off.	approval_mode: manual
tools.mcp_servers	Names of servers defined in the folder's .mcp.json.	mcp_servers: [calendar]
tools.tools_off	Tool names to turn off, as server:tool.	tools_off: ["calendar:delete_event"]
behavior.tone	default, professional or friendly.	tone: friendly
behavior.engagement_frequency	low, medium or high.	engagement_frequency: low

Without a catalex.yaml, the repo imports as one agent named like the listing, with the repo root as its folder.

Limits

• The file must be at most 256 KiB.
• It may nest at most 64 levels deep and expand to at most 100,000 values. YAML anchors, aliases and merge keys (<<) count toward the budget and are resolved like any other value; a key written in the mapping wins over a merged one.
• A key may appear only once in the file, at any depth.
• At most 10 agents are imported.
• A .mcp.json larger than 1 MiB is treated as defining no servers.

What CatalEx checks

Checking never refuses a repo. CatalEx replaces each invalid setting with its default and reports it as a finding.

In the app, the account that listed the repo sees the warning icon (Setup has some issues) on its card. Only that account sees it; people importing the agent never do. The dialog lists each problem in plain words, such as Model name "x y" is not a valid model name. CatalEx uses default settings where a value is invalid. It rebuilds the findings at each refresh and checks every listed repo at least daily, so a fix you push shows up on the next daily refresh.

• File as a whole. An unreadable file, a file over the size limit, a file over the nesting or values limit, a duplicate key, a missing version or a version other than 1 is treated as no file. The repo then imports as one default agent.
• Unknown or wrong values. An unknown key is ignored. A wrong type or a value outside the table is replaced by the default (approval_mode becomes inherit).
• Folders. CatalEx normalizes a folder first, so ./x/ becomes x. A folder that is absolute, contains .., passes through a symbolic link, does not exist or is a file falls back to the repo root.
• Pictures. A picture that is missing, not PNG or JPEG (any letter case in the extension), too large or outside the repo is dropped.
• Switches. terminal_access, sandbox and command_internet accept on and off plain, in quotes, or as YAML true (on) and false (off).
• Tool servers. Names in mcp_servers are checked against the mcpServers object of the folder's .mcp.json (.mcp.json for the root, FOLDER/.mcp.json otherwise). A missing file, invalid JSON or no mcpServers object means no server is defined, so every name is reported. The setting is kept.
• Names. A name is kept as written. An empty name, one of only spaces, or one over 60 characters is invalid, and that agent is skipped. When no agent is valid, the repo imports as one default agent. Entries count by position in the list, valid or not: from the eleventh on they are ignored, with one finding.
• Extra folders. tools.extra_folders in any form is ignored. Only the person can give an agent other folders.
• Instructions and README. A missing AGENTS.md, CLAUDE.md or SKILL.md for an agent, or a missing README.md, produces a finding but changes nothing.

A repo with no catalex.yaml has no findings.

Never put secrets in the file

CatalEx never uses a secret from catalex.yaml. A key named token, secret, password, api_key, apikey or starting with credential (any letter case), or a value starting sk-, ghp_, gho_, github_pat_, xox or AKIA, is ignored at every depth and reported as a finding. The value is never shown in the message. A repo is public, so anything you commit is public too. Ask the person for credentials in the first chat instead.

What CatalEx never runs

Importing clones the repo and checks out one exact commit. CatalEx never runs git hooks, install scripts, package managers or submodule fetches, and the Marketplace never executes anything from your repo. Your code runs only when the person talks to the agent, under the tool settings the person approved.

How updates reach importers

CatalEx offers the newest default-branch commit. An importer on an older commit sees Update on the Marketplace card and an update icon on the agent's tile on the Agents page. Update is a fresh install: CatalEx clones the new commit into a new folder and moves the agents there, keeping their chats, channels and the person's own settings. Nothing is copied from the old folder, so keep data that must survive an update outside the agent folder.

Tips

• Make the agent work from a fresh clone with no setup step.
• Declare provider and model as preferences, and test under Claude and Codex.
• Keep one agent per folder, each with its own instructions file.