Skills

Overview

Every AI employee on Oya is powered by skills — small, self-contained modules that define what the agent can do. When a user sends a message, the agent decides which skills to call based on the conversation context, executes them, and weaves the results into its response.

Skills are defined using a simple SKILL.md file format with YAML frontmatter and an optional Python script. They are organized into three tiers:

• Core — Always available. No setup required.
• Platform — Auto-enabled when you connect a gateway (Slack, Discord, Telegram, Gmail, Google Calendar, Google Drive, ClickUp, Jira, LinkedIn, X, Apollo, Hunter.io, Instantly).
• Add-on — Opt-in marketplace skills for specialized integrations (DataForSEO, SEranking, Retool, Xano, etc.).

Execution Types

Skills run in one of four ways, depending on how they are defined:

Tool (In-Process)

Tool skills run directly inside the Oya backend process. They are fast, lightweight async functions — ideal for simple operations like web searches, API calls, or database lookups. No sandbox is needed.

• Fastest execution — no container startup.
• Used by core skills: Memory, Knowledge Base, Web Search, REST API Call.
• Defined in the builtin/ directory with a Python async function.

Sandbox (Isolated Python)

Sandbox skills run inside an isolated sandbox — a dedicated Python environment per agent. They can install pip packages, read/write files, and perform complex operations safely. Arguments are passed via the INPUT_JSON environment variable.

• Full Python environment with pip packages.
• Used by Text to Speech, all platform skills, and add-on skills.
• Can generate files (audio, images, reports) returned as download links.
• Each argument is also available as INPUT_<NAME> env var.

MCP (Model Context Protocol)

MCP skills connect to external MCP servers that expose tools via the Model Context Protocol. Tools are discovered automatically from the server and executed through the MCP client.

Core Skills

Core skills are auto-enabled for every new agent in skills mode. They require no API keys or configuration.

Memory

Reads and writes persistent facts about users, preferences, and context. Facts survive across conversations, letting the agent build up knowledge over time.

• read — Recall all stored facts for this agent.
• write — Save a new fact (e.g., "User prefers formal tone").

Knowledge Base

Searches the agent's uploaded documents using semantic search. Upload PDFs, URLs, or text files to the Knowledge Base tab, and the agent can answer questions from them.

Web Search

Searches the web for current information using the Tavily API. Returns the top 5 results with titles, URLs, and content snippets. Use this when users ask about recent events or need factual answers.

REST API Call

Makes HTTP requests to external REST APIs. Supports GET, POST, PUT, PATCH, DELETE with custom headers and JSON body. The agent can call any public or authenticated API on your behalf.

• url — Full URL to call.
• method — HTTP method (default: GET).
• headers — JSON string of request headers (e.g., Authorization).
• body — JSON string for request body (POST, PUT, PATCH).

Text to Speech

Converts text to an MP3 audio file using gTTS (free, no API key). The generated file is returned as a playable audio player in web chat, or as a native voice note in Telegram (when enabled).

Platform Skills

Platform skills are auto-enabled when you connect a gateway. They use the gateway's credentials — no extra setup needed.

Slack

• Send Message — Post messages to any Slack channel.
• Read Messages — Fetch recent messages from a channel.
• Search Messages — Search messages across the workspace.
• List Channels — List available channels.

Discord

• Send Message — Post messages to any Discord channel.
• Read Messages — Fetch recent messages from a channel.
• List Channels — List server channels.

Telegram

• Send Message — Send messages to any Telegram chat.
• Read Updates — Fetch recent messages and updates.

Gmail

• Send Email — Compose and send emails from the connected account.
• Read Email — Read specific emails by ID or recent inbox.
• Search Email — Search emails by query string.
• Reply — Reply to an existing email thread.
• Forward — Forward an email to another recipient.
• Labels — Add or remove labels from emails.
• Drafts — Create and manage email drafts.
• Trash — Move emails to trash.
• Mark Read — Mark emails as read or unread.
• Get Thread — Retrieve a full email thread by ID.
• List Drafts — List all draft emails in the account.

Google Calendar

• List Events — List upcoming events with search, time range, and multi-calendar support.
• Get Event — Full event details including attendees, Meet link, and recurrence.
• Create Event — Create events with guests, Google Meet, recurrence, reminders, and timezone.
• Update Event — Reschedule, add guests, change fields, or add Meet to existing events.
• Delete Event — Cancel events with notification control.
• Quick Add — Natural language event creation (e.g., "Lunch with John tomorrow at noon").
• Find Free/Busy — Check availability for a time range.
• List Calendars — List all accessible calendars with timezone and access role.

Google Drive

• List Files — List files and folders in a directory.
• Search Files — Search files by name or content.
• Get File — Retrieve file metadata by ID.
• Create File — Create a new file.
• Upload File — Upload a file to Drive.
• Download File — Download a file from Drive.
• Create Folder — Create a new folder.
• Move File — Move a file to a different folder.
• Copy File — Create a copy of a file.
• Delete File — Move a file to trash.
• Share File — Share a file with users or groups.
• Manage Permissions — Update sharing permissions.
• Create Google Doc — Create a new Google Docs document.
• Export File — Export a Google Docs/Sheets/Slides file to another format.

ClickUp

• Manage spaces, folders, lists, tasks, subtasks, checklists, and dependencies.

Jira

• Create, update, search, and manage Jira issues across projects.

LinkedIn

• Get Profile — View your LinkedIn profile info.
• Create Post — Create text posts with visibility control (Public/Connections).
• Share URL — Share a URL with commentary.
• Delete Post — Delete a post by URN.
• Company Pages — Get company details and post on behalf of a company page.
• React — React to posts (Like, Praise, Empathy, Interest, Appreciation, Entertainment).
• Comment — Comment on posts.
• Connections — Get connection count.

X (Twitter)

• Get Profile — View your X profile info.
• Create Tweet — Post a new tweet.
• Reply — Reply to a tweet.
• Delete Tweet — Delete a tweet.
• Retweet — Retweet a tweet.
• Like / Unlike — Like or unlike a tweet.
• Search — Search recent tweets by query.
• Get User — Look up a user by username.
• Get Tweet — Get a tweet by ID.

Apollo

• Search People — Find leads by title, location, industry, company size, and keywords.
• Search Organizations — Find companies matching criteria.
• Enrich Person — Get full contact details (email, phone, social profiles) for a person.

Hunter.io

• Domain Search — Find all professional emails at a company domain.
• Email Finder — Find a specific person's email by name and domain.
• Email Verifier — Verify deliverability with status, score, MX records, and SMTP check.
• Email Count — Count emails at a domain by department and seniority (free).

Instantly

• List Campaigns — Browse campaigns with status and search filters.
• Get Campaign — Get campaign details.
• Add Lead / Add Leads Bulk — Add leads with personalization and custom variables.
• List Leads — List leads in a campaign with status and interest signals.
• Launch / Pause Campaign — Control campaign sending.
• Campaign Analytics — Track opens, replies, bounces, and unsubscribes.
• List Accounts — View connected sending accounts and warmup status.

Add-on Skills

Add-on skills are opt-in integrations available in the Skills step of the Agent Builder. They require credentials and sometimes per-agent configuration.

• DataForSEO — Keyword research, on-page analysis, backlinks, domain age.
• SEranking — SEO audit tools and rank tracking.
• Retool — Read-only PostgreSQL queries via Retool database.
• Xano — No-code database and API integration.
• Jira — Full project management: create, get, update, search issues, add comments, assign users, transition statuses, list projects, get project details, and list available statuses.

ClickUp

The ClickUp add-on provides 11 actions for project management:

• Create Task — Create tasks in any list.
• Get Task — Retrieve task details by ID.
• Update Task — Modify task properties.
• List Tasks — List tasks in a list or folder.
• Create List — Create new lists in a space or folder.
• Get Folders — Retrieve folders in a space.
• Get Spaces — List spaces in a workspace.
• Add Comment — Add comments to tasks.
• Get Workspaces — List available workspaces.
• Batch Create — Create multiple tasks at once from a plan.
• Delete Task — Remove a task by ID.

Creating Custom Skills

You can create your own skills directly from the Agent Builder. In the Skills step, click the Create Skill card to open the skill generator.

Type a plain-English description of what you want the skill to do — for example, "Check Bitcoin price from CoinGecko API" or "Send a webhook to my server with a custom payload." Press Generate (or Cmd+Enter) and the system will create a complete skill with SKILL.md frontmatter, tool schema, and a Python script.

After generation, the skill is auto-installed and the Skill Editor opens automatically so you can review and edit all files — the SKILL.md metadata, scripts, references, and configuration. The skill immediately appears in the Your skills section and can be toggled on for any agent.

Importing Skills

In addition to creating skills from scratch, you can import existing skills from GitHub or as ZIP files. Click the Import Skill card in the Skills step.

Import from GitHub

Paste a GitHub URL and Oya will download and import the skill automatically. Supported URL formats:

• Repository URL — https://github.com/owner/repo (imports the entire repo as a skill)
• Subfolder URL — https://github.com/owner/repo/tree/main/skills/my-skill (imports just that subfolder)
• Direct ZIP URL — https://github.com/owner/repo/archive/refs/heads/main.zip

This is compatible with the Anthropic Agent Skills spec ( agentskills.io), so you can import skills from the anthropics/skills repository or any repo following the spec.

Import from ZIP

Upload a .zip or .skill file containing a skill folder. The ZIP should contain a SKILL.md file at the root (or one level deep) along with any scripts, references, and assets.

After import, a summary shows the skill name, description, and a breakdown of imported files by type (scripts, references, assets). Click Import Another to import more, or close the dialog to return to the catalog.

Editing Skills

Every skill can be inspected and edited through the Skill Editor — a multi-file editor that opens as a side panel. Click Edit on any custom skill card, or View on a system skill (read-only).

The editor has a file tree sidebar on the left and a code editor on the right. Files are organized into sections:

• Metadata — SKILL.md (the skill definition with YAML frontmatter).
• Scripts — Python, JavaScript, or TypeScript files that the skill executes.
• References — Markdown or text files uploaded to the sandbox as additional LLM context.
• Assets — Templates, data files, or other resources available to the script at runtime.
• Config — requirements.txt for pip dependencies.

You can add new files to any section, delete files you no longer need, and edit any file with syntax highlighting. The editor auto-detects the language from the file extension (Python, JavaScript, TypeScript, JSON, YAML, Markdown).

Click Save to persist your changes. The editor tracks which files have been modified and only sends the diff. A fullscreen toggle expands the editor to fill the entire screen.

Skills Catalog UI

The Skills step in the Agent Builder provides a full catalog interface for browsing, searching, and managing skills:

• Search — Full-text search across skill names, descriptions, IDs, and categories.
• Category filter — Dynamic filter buttons for each skill category (communication, seo, voice, etc.).
• Organization — Skills are grouped into Core (always enabled), Enabled add-ons, Your skills (custom, not enabled), and Available catalog.
• Create Skill — Describe what the skill should do and AI generates the full implementation. Opens in the Skill Editor after creation.
• Import Skill — Import skills from GitHub URLs or ZIP files, including Anthropic Agent Skills spec-compatible skills.
• MCP Server — Connect external MCP-compatible tool servers that expose tools via the Model Context Protocol.
• Edit / View — Each skill card has always-visible Edit (custom skills) or View (system skills) buttons that open the multi-file Skill Editor.
• Uninstall — Remove custom skills you no longer need.

SKILL.md Format

Every skill is defined by a single SKILL.md file with YAML frontmatter and a markdown body. The frontmatter contains all the metadata the system needs to register, display, and execute the skill.

Frontmatter Fields

Tool Schema

The tool_schema follows the OpenAI function-calling format. It tells the LLM what the skill does, what parameters it accepts, and which are required. The LLM uses this schema to decide when and how to invoke the skill.

Catalog Type

• core — Auto-enabled for every agent. No credentials needed.
• platform — Auto-enabled when the matching gateway is connected. Uses gateway credentials.
• addon — Shown in the Skills marketplace. Requires explicit enablement and credentials.

Sandbox Scripts

Sandbox skills can include a single script.py or a multi-file structure with multiple scripts, references, and assets. Scripts run in an isolated Python environment with pip packages installed from the requirements field and auto-detected imports.

Multi-File Skills

Skills can contain multiple files organized into directories:

• scripts/ — Python files that the skill executes. All script subdirectories are added to PYTHONPATH so scripts can import each other.
• references/ — Markdown or text docs uploaded to the sandbox for LLM context. Useful for API guides, style docs, or example data.
• assets/ — Templates, data files, or other resources available to scripts at runtime.

The entry_point field in SKILL.md specifies which script to run (defaults to scripts/main.py or script.py). All files are uploaded to the sandbox preserving their relative paths, so scripts can import shared modules and read asset files using relative paths.

Receiving Inputs

Arguments from the LLM tool call are passed via environment variables:

• INPUT_JSON — Full JSON string of all parameters.
• INPUT_<NAME> — Each parameter also set individually (uppercased).

Returning Results

Print your result to stdout. The agent receives whatever you print as the skill's response. JSON output is recommended for structured data.

Example: Text to Speech

Config Schema

Add-on skills can define a config_schema that creates a per-agent configuration form in the Agent Builder. This lets users customize skill behavior without editing code.

Supported field types: string, number, boolean, select, and text (multiline). Fields can be organized into groups that render as separate sections.

Credentials & Resources

Skills that need API keys or secrets declare them in resource_requirements. When a user enables the skill, they are prompted to provide these values. The values are stored encrypted and injected as environment variables at runtime.

How Skills Resolve at Runtime

When a user sends a message, the system resolves the full set of available skills for the agent:

• 1. Explicitly enabled skills — Skills toggled on in the Agent Builder.
• 2. Gateway skills — Platform skills auto-injected from active gateways.
• 3. MCP tools — Discovered from connected MCP servers.

Each resolved skill becomes an OpenAI-format tool passed to the LLM. The LLM decides which tools to call based on the user's message and the tool descriptions. Results are fed back into the conversation so the agent can synthesize a final response.

Exporting Skills

Skills can be exported as ZIP archives for sharing or backup. The export endpoint supports two formats:

• Oya format — Full SKILL.md with all Oya frontmatter fields (tool_schema, config_schema, resource_requirements, etc.) plus all scripts, references, and assets.
• Anthropic format — Minimal SKILL.md with only name, description, license, and compatibility fields, conforming to the Agent Skills spec at agentskills.io.

Optionally pass an agent_id to include the agent's knowledge base files as references/ in the exported archive, making the skill self-contained with all its context.

Anthropic Agent Skills Spec

Oya's SKILL.md format is a superset of the Anthropic Agent Skills spec. Skills created for the Anthropic spec can be imported directly — Oya adds default values for any missing Oya-specific fields (skill_type, category, catalog_type).

Additional Anthropic-compatible fields supported in SKILL.md frontmatter:

• license — SPDX license identifier (e.g., MIT, Apache-2.0).
• compatibility — Compatibility notes from the Anthropic spec.
• metadata — Arbitrary key-value metadata from the Anthropic spec.
• entry_point — Which script to run (e.g., scripts/main.py).
• allowed-tools — List of allowed MCP tools (Anthropic spec field).

oya CLI Tool

The oya CLI is a pip-installable command-line tool for managing skills from the terminal:

• oya import <github-url|zip-path> — Import a skill from GitHub or a local ZIP file.
• oya export <skill-id> <output-path> — Download a skill as a ZIP archive.
• oya list — List all skills in your account.