/build-omnigent

name: build-omnigent
description: Patterns and templates for generating valid Omnigent agent directories. Load when ready to create files.

Agent Generation

Use these patterns to generate a valid agent directory. Always generate the minimal set of files needed — don't over-engineer.

Every template below has been validated with the same parser/validator that `omnigent server` uses. If your environment exposes the `validate_agent` tool (the dedicated agent-authoring environment does), run it after generating files to confirm the spec loads. Load the **`omnigent-knowledge`** skill if you need the deeper field reference (executor types, os_env, guardrails, sandboxing).

Step 1: Choose a directory name

Use the agent name in kebab-case: `my-research-agent/`

Step 2: Generate config.yaml

Always include:

• `spec_version: 1`
• `name` (lowercase, hyphens OK)
• `description` (one sentence)
• `instructions` — path to a file (default `AGENTS.md`) or inline text.

(`prompt:` is an accepted alias; `instructions:` wins if both are set.)

• `executor` — how the agent runs. See Step 2a.

Include if needed:

• `tools.builtins` — built-in tools. The current set is `download_file`,

`export_agent`, `list_files`, `search_conversations`, `upload_file`, `web_fetch`, `web_search`. If the `list_builtin_tools` tool is available, call it for the authoritative live set rather than trusting this list.

• `tools.agents` — sub-agents (must match `agents/` subdirectories).
• `os_env` — filesystem/shell access for harness agents (see the

shell-capable template).

• `interaction.modalities` — if the agent handles images or files.
• `guardrails` — runtime policy gates (see `omnigent-knowledge`).

Step 2a: Choose an executor

`executor.type` must be one of **`claude_sdk`**, **`agents_sdk`**, or **`omnigent`**. There is **no `llm` executor** — do not use it.

| Need | executor | |------|----------| | A fresh, simple LLM agent (default) | `claude_sdk` (Anthropic) or `agents_sdk` (OpenAI), in-process | | Existing Claude SDK / OpenAI Agents SDK code | `claude_sdk` / `agents_sdk` | | A CLI/coding harness, shell + file tools, sub-agents | `omnigent` + a `config.harness` |

When `executor.type: omnigent`, **`config.harness` is required** and must be one of: `claude-native` (Claude Code, full coding tools), `claude-sdk`, `codex-native`, `codex`, `openai-agents`, `open-responses`, `pi`. (`claude` is an alias for `claude-native`.)

Model selection is optional — if omitted, the executor resolves the provider's default model from the configured credentials (e.g. an Anthropic key, a Claude subscription, or a Databricks profile). Pin one only when asked; see `omnigent-knowledge` for `executor.model` / `auth`.

Step 3: Generate AGENTS.md

Write a focused system prompt:

• Identity: "You are a [role] that [does what]."
• Capabilities: what tools/skills are available
• Constraints: what NOT to do
• Style: how to communicate

Keep it under 500 words for a starter agent. The user can expand later.

Step 4: Generate skills (optional)

Only generate skills if the agent has distinct modes of operation. Each skill needs:

skills/<skill-name>/SKILL.md

With YAML frontmatter:

---
name: skill-name
description: One-line description of what this skill does.
---

Detailed instructions for when this skill is loaded...

Templates

Minimal agent (simplest — in-process SDK)

**config.yaml:**

spec_version: 1
name: {agent_name}
description: {description}
executor:
  type: claude_sdk      # or agents_sdk for OpenAI
instructions: AGENTS.md

**AGENTS.md:**

You are {agent_name}, {description}.

Answer questions clearly and concisely. If you don't know something,
say so rather than guessing.

Agent with web search

**config.yaml:**

spec_version: 1
name: {agent_name}
description: {description}
executor:
  type: claude_sdk
tools:
  builtins:
    - web_search        # one of the builtins listed in Step 2
interaction:
  modalities:
    input: [text]
    output: [text]
instructions: AGENTS.md

Harness agent with shell + filesystem access

Use the `omnigent` executor with a coding harness when the agent needs to run commands and read/write files. `os_env` grants OS access; the harness exposes `sys_os_read` / `sys_os_write` / `sys_os_edit` / `sys_os_shell`.

**config.yaml:**

spec_version: 1
name: {agent_name}
description: {description}
executor:
  type: omnigent
  config:
    harness: claude-native
    # Headless runs can't answer approval prompts — bypass them. Pair
    # with a read-only prompt and/or a blast_radius guardrail for safety.
    permission_mode: bypassPermissions   # codex-native uses `yolo: true`
os_env:
  type: caller_process
  cwd: .
  sandbox:
    type: none          # or linux_bwrap / darwin_seatbelt to sandbox
instructions: AGENTS.md

Agent with MCP server integration

**Directory structure:**

{agent_name}/
  config.yaml
  AGENTS.md
  tools/
    mcp/
      github.yaml

**config.yaml:**

spec_version: 1
name: {agent_name}
description: {description}
executor:
  type: claude_sdk
instructions: AGENTS.md

**tools/mcp/github.yaml:**

transport: http
url: https://your-mcp-server.example.com/sse
headers:
  Authorization: Bearer ${{{mcp_token_var}}}

Multi-agent system with sub-agents

Sub-agents need the `omnigent` executor (it provides the spawn tools).

**Directory structure:**

{agent_name}/
  config.yaml
  AGENTS.md
  agents/
    {sub_agent_1}/
      config.yaml
    {sub_agent_2}/
      config.yaml

**Parent config.yaml:**

spec_version: 1
name: {agent_name}
description: {description}
executor:
  type: omnigent
  config:
    harness: claude-sdk
tools:
  agents:
    - {sub_agent_1}
    - {sub_agent_2}
instructions: AGENTS.md

**Sub-agent config (agents/{sub_agent_1}/config.yaml):**

spec_version: 1
name: {sub_agent_1}
description: {sub_agent_1_description}
executor:
  typ