[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7CTCMCF05TFFD0XFCFTDJ3M":3,"skill-same:01M7CTCMCF05TFFD0XFCFTDJ3M":44},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":29,"install":30,"resources":43},"01M7CTCMCF05TFFD0XFCFTDJ3M","omnigent-knowledge",null,"Deep reference on Omnigent config format, executor types, skill\u002Ftool structure, and conventions. Load when you need to look up how the platform works.","roland-id-au\u002Fomniagent","roland-id-au","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F2590653?v=4","01M7CT4DEBVK4R185WFWCWN4JD","Buck Chancey","01M7CT4DFGWX49CGE347EF4V6T",0,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Froland-id-au\u002Fomniagent\u002Fblob\u002Fdeploy\u002Froland-id-au-omniagent\u002Fwork\u002Fomnigent-main\u002Fomnigent\u002Fonboarding\u002Fagent\u002Fskills\u002Fomnigent-knowledge\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: omnigent-knowledge\ndescription: Deep reference on Omnigent config format, executor types, skill\u002Ftool structure, and conventions. Load when you need to look up how the platform works.\n---\n\n# Omnigent Knowledge Base\n\n## What is Omnigent?\n\nAgent plane is a server that hosts, manages, and executes agents via an\nOpenResponses-compatible API. Users create **agent directories** (also\ncalled agent images) that contain configuration, instructions, skills,\nand tools. The server loads these directories and serves them via HTTP.\n\n## Agent Directory Layout\n\n```\nmy-agent\u002F\n├── config.yaml          # REQUIRED — agent spec\n├── AGENTS.md            # Recommended — instructions\u002Fpersonality\n├── skills\u002F              # Optional — load-on-demand skills\n│   └── \u003Cdir>\u002F           # Free-form; skill name comes from SKILL.md\n│       └── SKILL.md\n├── tools\u002F               # Optional — packaged tools\n│   ├── python\u002F          # Local Python tools (auto-discovered *.py)\n│   ├── typescript\u002F      # Local TypeScript tools (auto-discovered *.ts)\n│   └── mcp\u002F             # MCP server declarations (*.yaml)\n└── agents\u002F              # Optional — sub-agent directories (recursive)\n    └── \u003Cdir>\u002F           # Free-form; sub-agent name comes from config.yaml\n        ├── config.yaml\n        └── ...\n```\n\n## config.yaml Reference\n\nThe only required file. All fields except `spec_version` are optional.\n\n```yaml\nspec_version: 1               # REQUIRED, must be 1\n\nname: my-agent                # Display name\ndescription: Does X and Y.    # One-line summary\n\n# Instructions — path to a file or inline text.\n# Default: looks for AGENTS.md in the agent directory.\ninstructions: AGENTS.md\n\nexecutor:\n  # REQUIRED area. type must be one of: claude_sdk | agents_sdk | omnigent.\n  # There is NO `llm` executor type.\n  type: claude_sdk     # Anthropic Claude SDK, in-process (simplest)\n  # type: agents_sdk   — OpenAI Agents SDK, in-process\n  # type: omnigent     — subprocess harness; requires config.harness below\n\n  # Only for type: omnigent — pick the harness that runs the loop.\n  # One of: claude-native | claude-sdk | codex-native | codex |\n  #         openai-agents | open-responses | pi\n  # config:\n  #   harness: claude-native\n  #   permission_mode: bypassPermissions   # claude-native headless\n  #   yolo: true                           # codex-native headless\n\n  # Model is OPTIONAL — omit to use the configured provider's default.\n  # Pin one directly on the executor when needed:\n  # model: anthropic\u002Fclaude-sonnet-4-20250514   # LiteLLM provider\u002Fmodel\n  # model: databricks-claude-opus-4-7           # or a serving-endpoint name\n  # connection:                                 # provider credentials\n  #   api_key: ${ANTHROPIC_API_KEY}\n  # auth:                                        # or Databricks profile auth\n  #   type: databricks\n  #   profile: oss\n\n  timeout: 3600        # Task deadline in seconds (default: 3600)\n  max_iterations: 1000 # Max LLM calls per task (default: 1000)\n\n# os_env — grant filesystem\u002Fshell access (harness agents). Exposes\n# sys_os_read \u002F sys_os_write \u002F sys_os_edit \u002F sys_os_shell.\nos_env:\n  type: caller_process\n  cwd: .\n  sandbox:\n    type: none         # or linux_bwrap \u002F darwin_seatbelt to sandbox\n\n# guardrails — runtime policy gates (optional).\nguardrails:\n  ask_timeout: 86400   # seconds to wait on an approval prompt\n  policies:\n    blast_radius:\n      type: function\n      function:\n        path: omnigent.inner.nessie.policies.blast_radius\n\ninteraction:\n  conversational: true   # Maintain turn history (default: true)\n  modalities:\n    input: [text, image, file]   # default: [text]\n    output: [text]               # default: [text]\n\ntools:\n  # Sub-agents this agent can spawn (declared names of agents\u002F sub-agents)\n  agents:\n    - researcher\n    - summarizer\n\n  # Built-in tools — string name or dict with config\n  builtins:\n    - web_search                 # auto-detects backend based on model provider\n    - terminal_run               # persistent bash shell scoped to the conversation\n    - upload_file\n    - search_conversations\n\n  timeout: 60          # Default tool timeout in seconds\n\nparams:                # Arbitrary key-value (readable by skills\u002Ftools)\n  max_results: 10\n```\n\n## Executor Types\n\n| Type | When to use | How it works |\n|------|------------|--------------|\n| `claude_sdk` | New simple agents; existing Claude SDK code | In-process Anthropic Claude SDK; it manages its own loop |\n| `agents_sdk` | New simple agents; existing OpenAI Agents SDK code | In-process OpenAI Agents SDK runner |\n| `omnigent` | Coding\u002FCLI harnesses, shell + file tools, sub-agents | Spawns a subprocess harness selected by `config.harness` |\n\n**There is no `llm` executor type** — the only valid values are\n`claude_sdk`, `agents_sdk`, and `omnigent`. For **most new simple agents**,\nuse `claude_sdk` (or `agents_sdk`) — in-process, no extra config. Use\n`omnigent` when the agent needs a specific harness, shell\u002Ffile access, or\nsub-agents; it **requires** a `config.harness`:\n\n| `config.harness` | What it is |\n|------------------|------------|\n| `claude-native` (alias `claude`) | Claude Code — full coding tools, native permissions |\n| `claude-sdk` | Claude Agent SDK loop |\n| `codex-native` \u002F `codex` | Codex CLI \u002F harness |\n| `openai-agents` | OpenAI Agents harness (any gateway model) |\n| `open-responses` | OpenResponses-compatible harness |\n| `pi` | Headless multi-model worker (bridged `sys_os_*` tools) |\n\n## AGENTS.md Format\n\nFree-form markdown. This becomes the agent-authored portion of the system\nprompt; Omnigent may append framework-owned lifecycle or metadata instructions\nat runtime. Best practices:\n\n- Start with a clear identity statement (\"You are a ...\")\n- List capabilities and constraints\n- Reference skills by name (\"You have a skill called deep-research\")\n- Reference sub-agents if any (\"You can spawn the fact_checker agent\")\n- Keep it focused — the model reads this on every turn\n\n## Skills Format\n\nEach skill lives in `skills\u002F\u003Cdir>\u002FSKILL.md` (the directory name is free-form\nand need not match the skill's `name`):\n\n```markdown\n---\nname: deep-research\ndescription: Investigate a topic in depth using web search and source synthesis.\n---\n\nWhen researching a topic:\n\n1. Search broadly first using web search...\n2. Cross-reference multiple sources...\n```\n\nRules:\n- YAML frontmatter with `name` and `description` (both required)\n- `name` must be lowercase and use `[a-z0-9-]+`; it need not match the\n  directory name (the directory is where the skill's files load from)\n- Body is markdown instructions loaded on demand by the agent\n- Referenced in AGENTS.md or config.yaml\n\n## Tools\n\n### Built-in tools\n\nCall `list_builtin_tools` to get the current set of available\nbuilt-in tools and their descriptions. Do not rely on a hardcoded\nlist — new tools may be added at any time.\n\n**Tool recommendation guide:**\n\n- \"I want a research agent\" → `web_search` + `web_fetch`\n- \"I want a coding agent\" → `terminal_run` + `upload_file`\n- \"I want a data analysis agent\" → `terminal_run` + `upload_file` + `download_file`\n- \"I want a conversational assistant\" → no tools needed (or `web_search` for current info)\n- \"I want an agent that can access external APIs\" → consider MCP servers (see below)\n\n### MCP servers (external tool integrations)\n\nMCP (Model Context Protocol) lets agents connect to external services —\ndatabases, APIs, Slack, GitHub, etc. Each MCP server is declared as a\nYAML file in `tools\u002Fmcp\u002F`:\n\n```\nmy-agent\u002F\n  tools\u002F\n    mcp\u002F\n      github.yaml\n      slack.yaml\n```\n\n**MCP server config format** (`tools\u002Fmcp\u002Fgithub.yaml`):\n\n```yaml\ntransport: http\nurl: https:\u002F\u002Fmcp-server.example.com\u002Fsse\nheaders:\n  Authorization: Bearer ${GITHUB_TOKEN}\n```\n\n- `transport`: must be `http`\n- `url`: the MCP server's SSE endpoint URL\n- `headers`: optional auth headers (use `${ENV_VAR}` for secrets)\n\n**When to recommend MCP:**\n\n- User wants to connect to an external service (database, API, SaaS tool)\n- User mentions Slack, GitHub, Jira, Postgres, etc.\n- The integration isn't covered by built-in tools\n\n**Finding MCP servers:** Use `web_search` (if available) or `web_fetch`\nto search for available MCP servers. Good starting points:\n- https:\u002F\u002Fmodelcontextprotocol.io — official MCP directory\n- https:\u002F\u002Fgithub.com\u002Fmodelcontextprotocol — official GitHub org\n- Search for \"\u003Cservice-name> MCP server\" (e.g. \"Slack MCP server\",\n  \"Postgres MCP server\")\n\nIf the user mentions a specific service they want to connect to,\nuse `web_search` or `web_fetch` to find if an MCP server exists\nfor it and how to configure it.\n\n**What to tell the user:** MCP servers are external processes that\nexpose tools via HTTP. The user needs to run the MCP server separately\n(or use a hosted one) and provide the URL in the config.\n\n### Local tools (custom Python\u002FTypeScript)\n\nPython files in `tools\u002Fpython\u002F` are auto-discovered. Each\n`@tool`-decorated module-level function in those files becomes a\nseparate tool — one file may export many tools. The decorator\nderives the JSON schema from the function's type hints and\nGoogle-style docstring.\n\n```python\n# tools\u002Fpython\u002Fmy_tools.py\nfrom omnigent.tools import tool\n\n\n@tool\ndef my_tool(text: str, count: int = 1) -> str:\n    \"\"\"\n    Repeat the text count times.\n\n    Args:\n        text: The text to repeat.\n        count: Number of repetitions (default 1).\n    \"\"\"\n    return text * count\n```\n\nAuthoring rules:\n\n- Decorate a **module-level** function — not a class method,\n  lambda, or nested function (the decorator rejects those at\n  decoration time with a clear error).\n- Type hints on parameters drive the LLM-facing JSON schema. Use\n  concrete types — `Any` and `object` produce permissive schemas\n  with no validation.\n- The function name becomes the LLM-facing tool name. Names must\n  not collide with built-in tools or with other custom tools in\n  the same agent (collisions fail loud at agent load).\n- Both `def` and `async def` are supported. Sync `def` bodies are\n  wrapped in `asyncio.to_thread` automatically so they don't\n  block the event loop.\n- Pydantic `BaseModel` arguments are first-class — they get\n  expanded into the schema correctly with full validation.\n\n**When to recommend local tools:** When the user needs custom logic that\nisn't covered by builtins or MCP servers.\n\n## Example: Minimal Agent\n\n```yaml\nspec_version: 1\nname: my-assistant\ndescription: A helpful assistant.\nexecutor:\n  type: claude_sdk\ninstructions: |\n  You are a helpful assistant. Answer questions clearly and concisely.\n```\n\nThis is the simplest valid agent — a name, an executor, and instructions.\nNo model is pinned, so it uses the configured provider's default. No\nskills, no tools, no sub-agents.\n\n## Example: Research Agent with Tools and Skills\n\n```yaml\nspec_version: 1\nname: researcher\ndescription: A research agent that searches the web and synthesizes findings.\nexecutor:\n  type: agents_sdk\ntools:\n  builtins:\n    - web_search\n    - upload_file\ninteraction:\n  modalities:\n    input: [text, file]\n    output: [text]\ninstructions: AGENTS.md\n```\n\n## Sub-Agents (multi-agent systems)\n\nAn agent can spawn child agents to delegate tasks. Sub-agents are\nfull agents with their own config.yaml, living in the `agents\u002F`\ndirectory:\n\n```\nmy-agent\u002F\n  config.yaml\n  AGENTS.md\n  agents\u002F\n    researcher\u002F\n      config.yaml        # sub-agent spec — declares name: researcher\n    fact-check-worker\u002F\n      config.yaml        # declares name: fact-checker (dir may differ)\n```\n\n### Declaring sub-agents\n\nThe parent's config.yaml lists sub-agent names under `tools.agents`:\n\n```yaml\ntools:\n  agents:\n    - researcher\n    - fact-checker\n  builtins:\n    - web_search\n```\n\nEach name must be the declared `name` of a sub-agent under `agents\u002F`; the\ndirectory it lives in may differ. The **parent** must use\n`executor.type: omnigent` — that's what provides the spawn tools. Each\nsub-agent is a full agent and may use any executor (`claude_sdk`,\n`agents_sdk`, or `omnigent`).\n\n### Sub-agent config\n\nEach sub-agent has its own complete config.yaml:\n\n```yaml\n# agents\u002Fresearcher\u002Fconfig.yaml\nspec_version: 1\nname: researcher\ndescription: Sub-agent that searches the web for information.\nexecutor:\n  type: claude_sdk\ntools:\n  builtins:\n    - web_search\n    - web_fetch\ninstructions: |\n  You are a researcher. When given a topic, search the web\n  and return a summary with sources.\n```\n\n### How spawning works\n\nThe parent agent gets `sys_session_send` (singular), `check_task`,\nand `sys_cancel_task` tools automatically when sub-agents are\ndeclared. The parent's AGENTS.md should reference them:\n\n```markdown\nYou have two sub-agents you can delegate to:\n- **researcher** — searches the web for information\n- **fact-checker** — verifies claims with evidence\n\nCall `sys_session_send(type=\"\u003Cname>\", input=\"\u003Ctask>\")` to\ndispatch one. Emit multiple `sys_session_send` tool calls in the\nsame response to run sub-agents in parallel. Each result auto-\ndelivers as a system message when ready — `check_task` polls,\n`sys_cancel_task` aborts.\n```\n\n### When to recommend sub-agents\n\n- User wants specialized roles (researcher + summarizer + reviewer)\n- User wants parallel execution (search multiple sources at once)\n- User wants separation of concerns (each sub-agent has focused instructions)\n\n**For simple agents, sub-agents are overkill.** Only suggest them when\nthe user describes a workflow with distinct steps or roles.\n\n## Running an Agent\n\nOnce the agent directory is created:\n\n```bash\n# Start the server with the agent pre-registered\nap server --agent .\u002Fmy-agent\u002F\n\n# Or deploy to a running server\nap deploy .\u002Fmy-agent\u002F --server http:\u002F\u002Flocalhost:6767\n```\n","# Omnigent Knowledge Base\n\n## What is Omnigent?\n\nAgent plane is a server that hosts, manages, and executes agents via an\nOpenResponses-compatible API. Users create **agent directories** (also\ncalled agent images) that contain configuration, instructions, skills,\nand tools. The server loads these directories and serves them via HTTP.\n\n## Agent Directory Layout\n\n```\nmy-agent\u002F\n├── config.yaml          # REQUIRED — agent spec\n├── AGENTS.md            # Recommended — instructions\u002Fpersonality\n├── skills\u002F              # Optional — load-on-demand skills\n│   └── \u003Cdir>\u002F           # Free-form; skill name comes from SKILL.md\n│       └── SKILL.md\n├── tools\u002F               # Optional — packaged tools\n│   ├── python\u002F          # Local Python tools (auto-discovered *.py)\n│   ├── typescript\u002F      # Local TypeScript tools (auto-discovered *.ts)\n│   └── mcp\u002F             # MCP server declarations (*.yaml)\n└── agents\u002F              # Optional — sub-agent directories (recursive)\n    └── \u003Cdir>\u002F           # Free-form; sub-agent name comes from config.yaml\n        ├── config.yaml\n        └── ...\n```\n\n## config.yaml Reference\n\nThe only required file. All fields except `spec_version` are optional.\n\n```yaml\nspec_version: 1               # REQUIRED, must be 1\n\nname: my-agent                # Display name\ndescription: Does X and Y.    # One-line summary\n\n# Instructions — path to a file or inline text.\n# Default: looks for AGENTS.md in the agent directory.\ninstructions: AGENTS.md\n\nexecutor:\n  # REQUIRED area. type must be one of: claude_sdk | agents_sdk | omnigent.\n  # There is NO `llm` executor type.\n  type: claude_sdk     # Anthropic Claude SDK, in-process (simplest)\n  # type: agents_sdk   — OpenAI Agents SDK, in-process\n  # type: omnigent     — subprocess harness; requires config.harness below\n\n  # Only for type: omnigent — pick the harness that runs the loop.\n  # One of: claude-native | claude-sdk | codex-native | codex |\n  #         openai-agents | open-responses | pi\n  # config:\n  #   harness: claude-native\n  #   permission_mode: bypassPermissions   # claude-native headless\n  #   yolo: true                           # codex-native headless\n\n  # Model is OPTIONAL — omit to use the configured provider's default.\n  # Pin one directly on the executor when needed:\n  # model: anthropic\u002Fclaude-sonnet-4-20250514   # LiteLLM provider\u002Fmodel\n  # model: databricks-claude-opus-4-7           # or a serving-endpoint name\n  # connection:                                 # provider credentials\n  #   api_key: ${ANTHROPIC_API_KEY}\n  # auth:                                        # or Databricks profile auth\n  #   type: databricks\n  #   profile: oss\n\n  timeout: 3600        # Task deadline in seconds (default: 3600)\n  max_iterations: 1000 # Max LLM calls per task (default: 1000)\n\n# os_env — grant filesystem\u002Fshell access (harness agents). Exposes\n# sys_os_read \u002F sys_os_write \u002F sys_os_edit \u002F sys_os_shell.\nos_env:\n  type: caller_process\n  cwd: .\n  sandbox:\n    type: none         # or linux_bwrap \u002F darwin_seatbelt to sandbox\n\n# guardrails — runtime policy gates (optional).\nguardrails:\n  ask_timeout: 86400   # seconds to wait on an approval prompt\n  policies:\n    blast_radius:\n      type: function\n      function:\n        path: omnigent.inner.nessie.policies.blast_radius\n\ninteraction:\n  conversational: true   # Maintain turn history (default: true)\n  modalities:\n    input: [text, image, file]   # default: [text]\n    output: [text]               # default: [text]\n\ntools:\n  # Sub-agents this agent can spawn (declared names of agents\u002F sub-agents)\n  agents:\n    - researcher\n    - summarizer\n\n  # Built-in tools — string name or dict with config\n  builtins:\n    - web_search                 # auto-detects backend based on model provider\n    - terminal_run               # persistent bash shell scoped to the conversation\n    - upload_file\n    - search_conversations\n\n  timeout: 60          # Default tool timeout in seconds\n\nparams:                # Arbitrary key-value (readable by skills\u002Ftools)\n  max_results: 10\n```\n\n## Executor Types\n\n| Type | When to use | How it works |\n|------|------------|--------------|\n| `claude_sdk` | New simple agents; existing Claude SDK code | In-process Anthropic Claude SDK; it manages its own loop |\n| `agents_sdk` | New simple agents; existing OpenAI Agents SDK code | In-process OpenAI Agents SDK runner |\n| `omnigent` | Coding\u002FCLI harnesses, shell + file tools, sub-agents | Spawns a subprocess harness selected by `config.harness` |\n\n**There is no `llm` executor type** — the only valid values are\n`claude_sdk`, `agents_sdk`, and `omnigent`. For **most new simple agents**,\nuse `claude_sdk` (or `agents_sdk`) — in-process, no extra config. Use\n`omnigent` when the agent needs a specific harness, shell\u002Ffile access, or\nsub-agents; it **requires** a `config.harness`:\n\n| `config.harness` | What it is |\n|------------------|------------|\n| `claude-native` (alias `claude`) | Claude Code — full coding tools, native permissions |\n| `claude-sdk` | Claude Agent SDK loop |\n| `codex-native` \u002F `codex` | Codex CLI \u002F harness |\n| `openai-agents` | OpenAI Agents harness (any gateway model) |\n| `open-responses` | OpenResponses-compatible harness |\n| `pi` | Headless multi-model worker (bridged `sys_os_*` tools) |\n\n## AGENTS.md Format\n\nFree-form markdown. This becomes the agent-authored portion of the system\nprompt; Omnigent may append framework-owned lifecycle or metadata instructions\nat runtime. Best practices:\n\n- Start with a clear identity statement (\"You are a ...\")\n- List capabilities and constraints\n- Reference skills by name (\"You have a skill called deep-research\")\n- Reference sub-agents if any (\"You can spawn the fact_checker agent\")\n- Keep it focused — the model reads this on every turn\n\n## Skills Format\n\nEach skill lives in `skills\u002F\u003Cdir>\u002FSKILL.md` (the directory name is free-form\nand need not match the skill's `name`):\n\n```markdown\n---\nname: deep-research\ndescription: Investigate a topic in depth using web search and source synthesis.\n---\n\nWhen researching a topic:\n\n1. Search broadly first using web search...\n2. Cross-reference multiple sources...\n```\n\nRules:\n- YAML frontmatter with `name` and `description` (both required)\n- `name` must be lowercase and use `[a-z0-9-]+`; it need not match the\n  directory name (the directory is where the skill's files load from)\n- Body is markdown instructions loaded on demand by the agent\n- Referenced in AGENTS.md or config.yaml\n\n## Tools\n\n### Built-in tools\n\nCall `list_builtin_tools` to get the current set of available\nbuilt-in tools and their descriptions. Do not rely on a hardcoded\nlist — new tools may be added at any time.\n\n**Tool recommendation guide:**\n\n- \"I want a research agent\" → `web_search` + `web_fetch`\n- \"I want a coding agent\" → `terminal_run` + `upload_file`\n- \"I want a data analysis agent\" → `terminal_run` + `upload_file` + `download_file`\n- \"I want a conversational assistant\" → no tools needed (or `web_search` for current info)\n- \"I want an agent that can access external APIs\" → consider MCP servers (see below)\n\n### MCP servers (external tool integrations)\n\nMCP (Model Context Protocol) lets agents connect to external services —\ndatabases, APIs, Slack, GitHub, etc. Each MCP server is declared as a\nYAML file in `tools\u002Fmcp\u002F`:\n\n```\nmy-agent\u002F\n  tools\u002F\n    mcp\u002F\n      github.yaml\n      slack.yaml\n```\n\n**MCP server config format** (`tools\u002Fmcp\u002Fgithub.yaml`):\n\n```yaml\ntransport: http\nurl: https:\u002F\u002Fmcp-server.example.com\u002Fsse\nheaders:\n  Authorization: Bearer ${GITHUB_TOKEN}\n```\n\n- `transport`: must be `http`\n- `url`: the MCP server's SSE endpoint URL\n- `headers`: optional auth headers (use `${ENV_VAR}` for secrets)\n\n**When to recommend MCP:**\n\n- User wants to connect to an external service (database, API, SaaS tool)\n- User mentions Slack, GitHub, Jira, Postgres, etc.\n- The integration isn't covered by built-in tools\n\n**Finding MCP servers:** Use `web_search` (if available) or `web_fetch`\nto search for available MCP servers. Good starting points:\n- https:\u002F\u002Fmodelcontextprotocol.io — official MCP directory\n- https:\u002F\u002Fgithub.com\u002Fmodelcontextprotocol — official GitHub org\n- Search for \"\u003Cservice-name> MCP server\" (e.g. \"Slack MCP server\",\n  \"Postgres MCP server\")\n\nIf the user mentions a specific service they want to connect to,\nuse `web_search` or `web_fetch` to find if an MCP server exists\nfor it and how to configure it.\n\n**What to tell the user:** MCP servers are external processes that\nexpose tools via HTTP. The user needs to run the MCP server separately\n(or use a hosted one) and provide the URL in the config.\n\n### Local tools (custom Python\u002FTypeScript)\n\nPython files in `tools\u002Fpython\u002F` are auto-discovered. Each\n`@tool`-decorated module-level function in those files becomes a\nseparate tool — one file may export many tools. The decorator\nderives the JSON schema from the function's type hints and\nGoogle-style docstring.\n\n```python\n# tools\u002Fpython\u002Fmy_tools.py\nfrom omnigent.tools import tool\n\n\n@tool\ndef my_tool(text: str, count: int = 1) -> str:\n    \"\"\"\n    Repeat the text count times.\n\n    Args:\n        text: The text to repeat.\n        count: Number of repetitions (default 1).\n    \"\"\"\n    return text * count\n```\n\nAuthoring rules:\n\n- Decorate a **module-level** function — not a class method,\n  lambda, or nested function (the decorator rejects those at\n  decoration time with a clear error).\n- Type hints on parameters drive the LLM-facing JSON schema. Use\n  concrete types — `Any` and `object` produce permissive schemas\n  with no validation.\n- The function name becomes the LLM-facing tool name. Names must\n  not collide with built-in tools or with other custom tools in\n  the same agent (collisions fail loud at agent load).\n- Both `def` and `async def` are supported. Sync `def` bodies are\n  wrapped in `asyncio.to_thread` automatically so they don't\n  block the event loop.\n- Pydantic `BaseModel` arguments are first-class — they get\n  expanded into the schema correctly with full validation.\n\n**When to recommend local tools:** When the user needs custom logic that\nisn't covered by builtins or MCP servers.\n\n## Example: Minimal Agent\n\n```yaml\nspec_version: 1\nname: my-assistant\ndescription: A helpful assistant.\nexecutor:\n  type: claude_sdk\ninstructions: |\n  You are a helpful assistant. Answer questions clearly and concisely.\n```\n\nThis is the simplest valid agent — a name, an executor, and instructions.\nNo model is pinned, so it uses the configured provider's default. No\nskills, no tools, no sub-agents.\n\n## Example: Research Agent with Tools and Skills\n\n```yaml\nspec_version: 1\nname: researcher\ndescription: A research agent that searches the web and synthesizes findings.\nexecutor:\n  type: agents_sdk\ntools:\n  builtins:\n    - web_search\n    - upload_file\ninteraction:\n  modalities:\n    input: [text, file]\n    output: [text]\ninstructions: AGENTS.md\n```\n\n## Sub-Agents (multi-agent systems)\n\nAn agent can spawn child agents to delegate tasks. Sub-agents are\nfull agents with their own config.yaml, living in the `agents\u002F`\ndirectory:\n\n```\nmy-agent\u002F\n  config.yaml\n  AGENTS.md\n  agents\u002F\n    researcher\u002F\n      config.yaml        # sub-agent spec — declares name: researcher\n    fact-check-worker\u002F\n      config.yaml        # declares name: fact-checker (dir may differ)\n```\n\n### Declaring sub-agents\n\nThe parent's config.yaml lists sub-agent names under `tools.agents`:\n\n```yaml\ntools:\n  agents:\n    - researcher\n    - fact-checker\n  builtins:\n    - web_search\n```\n\nEach name must be the declared `name` of a sub-agent under `agents\u002F`; the\ndirectory it lives in may differ. The **parent** must use\n`executor.type: omnigent` — that's what provides the spawn tools. Each\nsub-agent is a full agent and may use any executor (`claude_sdk`,\n`agents_sdk`, or `omnigent`).\n\n### Sub-agent config\n\nEach sub-agent has its own complete config.yaml:\n\n```yaml\n# agents\u002Fresearcher\u002Fconfig.yaml\nspec_version: 1\nname: researcher\ndescription: Sub-agent that searches the web for information.\nexecutor:\n  type: claude_sdk\ntools:\n  builtins:\n    - web_search\n    - web_fetch\ninstructions: |\n  You are a researcher. When given a topic, search the web\n  and return a summary with sources.\n```\n\n### How spawning works\n\nThe parent agent gets `sys_session_send` (singular), `check_task`,\nand `sys_cancel_task` tools automatically when sub-agents are\ndeclared. The parent's AGENTS.md should reference them:\n\n```markdown\nYou have two sub-agents you can delegate to:\n- **researcher** — searches the web for information\n- **fact-checker** — verifies claims with evidence\n\nCall `sys_session_send(type=\"\u003Cname>\", input=\"\u003Ctask>\")` to\ndispatch one. Emit multiple `sys_session_send` tool calls in the\nsame response to run sub-agents in parallel. Each result auto-\ndelivers as a system message when ready — `check_task` polls,\n`sys_cancel_task` aborts.\n```\n\n### When to recommend sub-agents\n\n- User wants specialized roles (researcher + summarizer + reviewer)\n- User wants parallel execution (search multiple sources at once)\n- User wants separation of concerns (each sub-agent has focused instructions)\n\n**For simple agents, sub-agents are overkill.** Only suggest them when\nthe user describes a workflow with distinct steps or roles.\n\n## Running an Agent\n\nOnce the agent directory is created:\n\n```bash\n# Start the server with the agent pre-registered\nap server --agent .\u002Fmy-agent\u002F\n\n# Or deploy to a running server\nap deploy .\u002Fmy-agent\u002F --server http:\u002F\u002Flocalhost:6767\n```\n",{"name":5,"description":7},"deploy\u002Froland-id-au-omniagent","83ee3dcd78468bbe3baf4bb264a0c99a53aa0fec","work\u002Fomnigent-main\u002Fomnigent\u002Fonboarding\u002Fagent\u002Fskills\u002Fomnigent-knowledge","https:\u002F\u002Fgithub.com\u002Froland-id-au\u002Fomniagent","https:\u002F\u002Fgithub.com\u002Froland-id-au","2026-09-16 03:15:34",{"source":8,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add roland-id-au\u002Fomniagent --skill omnigent-knowledge",{"tool":36,"command":37},"bunx","bunx skills add roland-id-au\u002Fomniagent --skill omnigent-knowledge",{"tool":39,"command":40},"pnpm","pnpm dlx skills add roland-id-au\u002Fomniagent --skill omnigent-knowledge","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Froland-id-au\u002Fomniagent\u002Fblob\u002Fdeploy\u002Froland-id-au-omniagent\u002Fwork\u002Fomnigent-main\u002Fomnigent\u002Fonboarding\u002Fagent\u002Fskills\u002Fomnigent-knowledge\u002FSKILL.md",true,[],[45,52,59,66,71,76],{"skillNo":46,"name":47,"nameZh":6,"description":48,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":49,"categories":50,"keywords":51,"publishedAt":19},"01M7CTDVNPM78AJ051GVDB44X5","deep-research","Research checklist and source-quality guidance for the archer e2e fixture.","https:\u002F\u002Fgithub.com\u002Froland-id-au\u002Fomniagent\u002Fblob\u002Fdeploy\u002Froland-id-au-omniagent\u002Fwork\u002Fomnigent-main\u002Ftests\u002Fresources\u002Fexamples\u002Farcher\u002Fskills\u002Fdeep-research\u002FSKILL.md",[],[],{"skillNo":53,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":56,"categories":57,"keywords":58,"publishedAt":19},"01M7CTDS8SPN8P5GK1Q4SCSY7K","pi-e2e-xyz-greet-c4a8d5","Test greeter — pi skills e2e. The unique suffix c4a8d5 appears in the skill name so a string match in the agent's output proves Pi loaded this skill.","https:\u002F\u002Fgithub.com\u002Froland-id-au\u002Fomniagent\u002Fblob\u002Fdeploy\u002Froland-id-au-omniagent\u002Fwork\u002Fomnigent-main\u002Ftests\u002Fresources\u002Fagents\u002Fpi_skills_none\u002Fskills\u002Fpi-e2e-xyz-greet-c4a8d5\u002FSKILL.md",[],[],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":19},"01M7CTDP4R9F06966W78WNZS2Y","pi-e2e-xyz-count-d2f6e1","Test counter — pi skills e2e. The unique suffix d2f6e1 appears in the skill name so a string match in the agent's output proves Pi loaded this skill.","https:\u002F\u002Fgithub.com\u002Froland-id-au\u002Fomniagent\u002Fblob\u002Fdeploy\u002Froland-id-au-omniagent\u002Fwork\u002Fomnigent-main\u002Ftests\u002Fresources\u002Fagents\u002Fpi_skills_none\u002Fskills\u002Fpi-e2e-xyz-count-d2f6e1\u002FSKILL.md",[],[],{"skillNo":67,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":19},"01M7CTDKP4W1Q18ZCY0XANDSEG","https:\u002F\u002Fgithub.com\u002Froland-id-au\u002Fomniagent\u002Fblob\u002Fdeploy\u002Froland-id-au-omniagent\u002Fwork\u002Fomnigent-main\u002Ftests\u002Fresources\u002Fagents\u002Fpi_skills_list\u002Fskills\u002Fpi-e2e-xyz-greet-c4a8d5\u002FSKILL.md",[],[],{"skillNo":72,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M7CTDFBMA3EBZNV7J380THGP","https:\u002F\u002Fgithub.com\u002Froland-id-au\u002Fomniagent\u002Fblob\u002Fdeploy\u002Froland-id-au-omniagent\u002Fwork\u002Fomnigent-main\u002Ftests\u002Fresources\u002Fagents\u002Fpi_skills_list\u002Fskills\u002Fpi-e2e-xyz-count-d2f6e1\u002FSKILL.md",[],[],{"skillNo":77,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":19},"01M7CTDCVTXTG72BKEV2HY7M6W","https:\u002F\u002Fgithub.com\u002Froland-id-au\u002Fomniagent\u002Fblob\u002Fdeploy\u002Froland-id-au-omniagent\u002Fwork\u002Fomnigent-main\u002Ftests\u002Fresources\u002Fagents\u002Fpi_skills_all\u002Fskills\u002Fpi-e2e-xyz-greet-c4a8d5\u002FSKILL.md",[],[]]