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, by the name each declares under agents/ (a sub-agent's directory name may differ from its name). 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/<dir>/SKILL.md The directory name is free-form and need not match the skill's name — the runtime identifies a skill by its frontmatter name and loads its files from whatever directory it sits in. 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 The parent needs the omnigent executor — that's what provides the spawn tools. Each sub-agent is a full agent and may use any executor. Directory structure: {agent_name}/ config.yaml AGENTS.md agents/ {sub_agent_1_dir}/ config.yaml {sub_agent_2_dir}/ config.yaml Directory names are free-form. A sub-agent's identity is the name in its own config.yaml , and that is what the parent lists in tools.agents — {sub_agent_1_dir} and {sub_agent_1} may differ. 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_dir}/config.yaml): spec_version: 1 name: { sub_agent_1 } description: { sub_agent_1_description } executor: # any executor works here — only the parent needs omnigent type: omnigent config: harness: claude-sdk instructions: | You are {sub_agent_1}. {sub_agent_1_instructions} Parent AGENTS.md should reference sub-agents: You have sub-agents you can delegate to: - **{sub _agent_ 1}** — {sub _agent_ 1 _description} - **{sub_agent_2}** — {sub_ agent _2_ description} Call `sys_session_send(type="<name>", input="<task>")` to dispatch a declared sub-agent. Emit multiple `sys_session_send` tool calls in the same response to run them in parallel; results arrive via the inbox. Environment variable naming conventions When pinning credentials with ${ENV_VAR} , map providers to their standard env var names: openai → OPENAI_API_KEY anthropic → ANTHROPIC_API_KEY gemini → GEMINI_API_KEY or GOOGLE_API_KEY groq → GROQ_API_KEY deepseek → DEEPSEEK_API_KEY xai → XAI_API_KEY mistral → MISTRAL_API_KEY databricks → DATABRICKS_TOKEN (or an auth.profile ) Validation checklist Before presenting the generated files to the user, verify (and if validate_agent is available, run it to confirm): spec_version: 1 is present name is set and uses lowercase + hyphens executor.type is one of claude_sdk , agents_sdk , omnigent If executor.type: omnigent , executor.config.harness is set to a valid harness instructions (or prompt ) points to a file that exists or is inline text When declaring tools.agents , the parent uses executor.type: omnigent , and each entry is the declared name of a sub-agent under agents/ (its directory name may differ; sub-agents may use any executor) tools.builtins names are from the known set (Step 2) — or, if list_builtin_tools is available, were confirmed against it Skill names use the [a-z0-9-]+ pattern (they need not match their directory names)