---
name: cookbook
description: Setup recipes for MCP servers, skills, agents, and workflows.
---

Help the user set up OMX extensions with practical recipes. First identify what they want to set up: an MCP server, skill, agent, workflow, hook, or external tool. If they already gave a target, proceed. If not, ask one short question with those choices.

Prefer project-local extension files when the request is for one repo, and user-level files when they want the setup available everywhere. Be precise about the path before showing content. Do not cover app settings, model settings, or server mode in this skill, except for the `hooksEnabled` switch when explaining hooks.

MCP servers are configured in JSON files. Load order is `~/.claude.json`, `.mcp.json`, `~/.omx/mcp.json`, then `.omx/mcp.json`; later entries with the same server id override earlier ones. Use `.omx/mcp.json` for one project and `~/.omx/mcp.json` for all projects. Avoid underscores in server ids, since MCP tool names are parsed as `Mcp_<serverId>_<toolName>`. The stdio shape is:

```json
{
  "mcpServers": {
    "server-id": {
      "command": "command",
      "args": ["arg1", "arg2"],
      "env": {
        "TOKEN": "${TOKEN}"
      }
    }
  }
}
```

For HTTP MCP servers, use `url` and optional `headers` instead of `command` and `args`:

```json
{
  "mcpServers": {
    "server-id": {
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TOKEN}"
      }
    }
  }
}
```

MCP config supports `command`, `args`, `url`, `env`, and `headers`. The `command`, `args`, `url`, `env` values, and `headers` values can use `${VAR}` or `${VAR:-default}`. After editing MCP config, restart OMX so the server connections and `Mcp_<serverId>_<toolName>` tools are loaded.

Skills live in directories with a `SKILL.md` file. Use `.omx/skills/name/SKILL.md` for one project and `~/.omx/skills/name/SKILL.md` for all projects. Claude-compatible skills are also loaded from `.claude/skills/name/SKILL.md` and `~/.claude/skills/name/SKILL.md`. Load order is built-in, `.omx` project, `.claude` project, `~/.omx` user, then `~/.claude` user. Built-in skills cannot be overridden, and earlier custom skills win over later skills with the same name. Use this shape:

```markdown
---
name: my-skill
description: What this skill helps with.
---

Write the reusable instructions here. Use $ARGUMENTS for everything passed after `/my-skill`, `$0` or $ARGUMENTS[0] for the first word, and `${OMX_SKILL_DIR}` for files stored next to this skill.
```

Skills can be invoked as `/my-skill` by the user or loaded with the `Skill` tool when model invocation is allowed. Optional frontmatter includes `user-invocable: false` to hide the slash command and `disable-model-invocation: true` to block loading through the `Skill` tool. Skills support `$ARGUMENTS`, `$ARGUMENTS[0]`-style indexed arguments, `$0`/`$1`-style positional arguments, `${OMX_SKILL_DIR}` or `${CLAUDE_SKILL_DIR}`, and `${OMX_SESSION_ID}` or `${CLAUDE_SESSION_ID}` placeholders. If a skill has no `$ARGUMENTS` or `$0`/`$1`-style placeholders and the user supplied arguments, OMX appends them as `ARGUMENTS: ...`. Keep skill names short, lowercase, and hyphenated.

Agents live as `.md` files directly inside `.omx/agents/` or `~/.omx/agents/`. Built-in agents cannot be overridden, and project agents take priority over user agents. Use an agent when the behavior should appear as an `Agent_<Name>` tool with its own parameters and optional tool restrictions. Show this minimal shape when relevant:

```markdown
---
name: MyAgent
description: Do one focused task.
allowBuiltinTools: [Read, Glob, Grep]
parameters:
  properties:
    question:
      type: string
      description: What to answer.
  required: [question]
---

Answer this focused question: {{question}}
```

Agent prompts use Handlebars variables from `parameters`. Tool filter fields are `allowBuiltinTools`, `allowExternalTools`, `allowBuiltinAgents`, `allowExternalAgents`, `allowMcpTools`, and `allowRemoteTools`; each can be `true` or a list of tool names without the `Agent_`, `Mcp_`, or `Remote_` prefix where applicable. Set `inheritContext: true` only when the agent needs the full current conversation instead of a fresh isolated session.

Workflows live as `.md` files directly inside `.omx/workflows/` or `~/.omx/workflows/`. Built-in workflows cannot be overridden, and project workflows take priority over user workflows for custom ids. A workflow id is the file name without `.md`, not the frontmatter `name`. Use a workflow when the user wants to define a broad assistant behavior preset. Tell the user the workflow id they created so they can select it from OMX's workflow UI or run OMX with `--workflow <id>`.

Use workflow frontmatter to allow tools when needed. Each field can be `true` or a list of tool names without the `Agent_`, `Mcp_`, or `Remote_` prefix where applicable:

```markdown
---
name: My Workflow
allowBuiltinTools: true
allowExternalTools: true
allowBuiltinAgents: true
allowExternalAgents: true
allowMcpTools: true
allowRemoteTools: true
---

Write the base behavior for this workflow here.
```

Hooks are JSON-configured lifecycle handlers. Use `.omx/hooks.json` for one project and `~/.omx/hooks/name.json` for all projects. Hook files are loaded at process startup, so restart OMX after editing them. Hooks can use command handlers or HTTP handlers. Supported events are `UserPromptSubmit`, `PreToolUse`, `PreCompact`, `PostCompact`, and `Stop`. `UserPromptSubmit`, `PreToolUse`, and `PreCompact` can block by returning `{ "block": true, "reason": "..." }`. `PreToolUse` handlers can include `tools` to match specific tool names. Hook failures are silently ignored. Command hooks receive the hook input JSON on stdin. HTTP hooks receive a POST with the hook input JSON. HTTP header values can reference allowed environment variables with `${VAR}` only, plus `allowedEnvVars`; do not use bare `$VAR`. If hooks are disabled, tell the user to turn on `hooksEnabled` from the TUI preferences, Web Settings, or app config.

Minimal project command hook config at `.omx/hooks.json`:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "tools": ["Bash"],
        "command": "node",
        "args": [".omx/hooks/check-bash.mjs"],
        "timeout": 30
      }
    ]
  }
}
```

Minimal user HTTP hook config at `~/.omx/hooks/audit.json`:

```json
{
  "hooks": {
    "Stop": [
      {
        "url": "https://example.com/omx/hooks/stop",
        "headers": {
          "Authorization": "Bearer ${HOOK_TOKEN}"
        },
        "allowedEnvVars": ["HOOK_TOKEN"],
        "timeout": 30
      }
    ]
  }
}
```

Minimal command hook script at `.omx/hooks/check-bash.mjs`:

```js
let input = '';
process.stdin.setEncoding('utf8');
process.stdin.on('data', chunk => {
  input += chunk;
});
process.stdin.on('end', () => {
  const hook = JSON.parse(input);
  if (hook.toolName === 'Bash') {
    process.stdout.write(JSON.stringify({block: true, reason: 'Bash is blocked for this project'}));
  }
});
```

External JavaScript tools live as `.js` or `.mjs` files directly inside `.omx/tools/` or `~/.omx/tools/`. User tools load first, then project tools, so project tools override same-named user tools. A default export without `name` uses the file name as the tool name. Use them only when the user needs a real executable tool, not just reusable instructions. If they only need guidance, recommend a skill instead. The minimal module shape is:

```js
export default {
  description: 'Do one focused task.',
  parameters: {
    properties: {
      input: {type: 'string', description: 'Input text.'}
    },
    required: ['input']
  },
  async execute(args, context) {
    return `Handled ${args.input} in ${context.cwd}`;
  }
};
```

When giving a recipe, include the exact file path and a complete minimal example. If the user asks you to create or update files, create parent directories as needed and keep the change narrow. End with a restart step after adding or changing MCP servers, skills, agents, workflows, hooks, or external tools, because discovery is initialized or cached by the running process. Include one short way to verify after restart: check slash command suggestions for skills, the workflow picker or settings for workflows, tool availability for agents, MCP servers, and external tools, or a harmless matching event for hooks.
