Skills & Tools
Three ways to give your agent new capabilities: tools, skills, and MCP servers. Each fits a different shape of need.
| Mechanism | Best for | Where it runs |
|---|---|---|
| Built-in tools | Filesystem, shell, web | Sandbox container |
| Custom tools | Your own JSON-schema’d action | Sandbox or your endpoint |
| Custom skills | Reusable prompt + reference files | Mounted into sandbox |
| MCP servers | Any MCP-spec capability set | Wherever the MCP server lives |
Built-in tools
Section titled “Built-in tools”The agent_toolset_20260401 toolset ships with: bash, read, write, edit, glob, grep, web_fetch, web_search. Add it to your agent and the model can do filesystem and shell work in the per-session container.
{ "name": "my-agent", "model": "claude-sonnet-4-6", "system": "...", "tools": [ { "type": "agent_toolset_20260401" } ]}web_fetch and web_search route through openma’s outbound proxy, so they work without the sandbox having direct internet access.
Custom tools
Section titled “Custom tools”Define a tool inline on the agent with a JSON schema:
{ "tools": [ { "type": "custom", "name": "lookup_user", "description": "Look up a user by their internal ID.", "input_schema": { "type": "object", "properties": { "user_id": { "type": "string" } }, "required": ["user_id"] }, "execution": { "type": "http", "endpoint": "https://internal.example.com/api/users/lookup", "method": "POST" } } ]}When the model calls the tool:
- The sandbox sends an outbound HTTPS request to your endpoint.
- If the endpoint host is bound to a Vault, the proxy injects the auth header automatically. The model never sees the credential.
- The response is fed back as the tool result.
You can also execute tools entirely inside the sandbox by setting execution: { type: "sandbox", command: "..." }.
Custom skills
Section titled “Custom skills”A skill is a SKILL.md describing the capability, plus any reference files (templates, schemas, examples) the model needs. The platform mounts everything at /home/user/.skills/{id}/ and adds a system prompt addition pointing the model at it.
Create a skill
Section titled “Create a skill”In the Console: Skills → New skill. Or via API:
curl -X POST "$OMA_BASE_URL/v1/skills" \ -H "Authorization: Bearer $OMA_API_KEY" \ -F "id=invoice-parser" \ -F "display_title=Invoice parser" \ -F "description=Extract structured data from supplier invoices." \ -F "files=@./SKILL.md" \ -F "files=@./schema.json" \ -F "files=@./example_invoice.pdf"What goes in SKILL.md
Section titled “What goes in SKILL.md”# Invoice parser
Use this skill when the user uploads a PDF or image of an invoice.
## How to extract
1. Read `/home/user/.skills/invoice-parser/schema.json` for the target shape.2. Use the `pdf` built-in skill to extract text.3. Match fields by label (e.g. "Total Due", "Invoice Number").4. Return JSON matching the schema.
## Examples
See `/home/user/.skills/invoice-parser/example_invoice.pdf` for a reference layout.Attach to an agent
Section titled “Attach to an agent”{ "skills": ["invoice-parser"]}Built-in skills
Section titled “Built-in skills”These ship out of the box and don’t need uploading: xlsx, pdf, docx, pptx, json, csv, sql, image. Reference them by id from your agent.
MCP servers
Section titled “MCP servers”Connect any Model Context Protocol server and openma auto-generates an mcp_<server>_<tool> for every capability the server exposes.
{ "mcp_servers": [ { "name": "github", "url": "https://mcp.example.com/github", "auth": { "type": "vault", "vault_id": "vault_abc" } } ]}The platform handshakes with the MCP server on agent load, caches the tool definitions, and exposes them on the next session. If the server is reachable behind auth, bind credentials in a Vault and reference it in auth.