Skills

Overview

Every OAgent on Oya is powered by skills: small, self-contained modules that define what the OAgent can do. When a user sends a message, the OAgent 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, WhatsApp, Instagram, Facebook Messenger, Gmail, Google Calendar, Google Drive, ClickUp, Jira, Attio, 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 OAgent. 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 OAgent 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 OAgent build up knowledge over time.

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

Knowledge Base

Searches the OAgent's uploaded documents using semantic search. Upload PDFs, URLs, or text files to the Knowledge Base tab, and the OAgent 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 OAgent 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.

WhatsApp

Send and receive WhatsApp messages through a connected Unipile account: ideal for conversational support or WhatsApp prospecting.

• List Chats: Browse recent WhatsApp conversations.
• Read Messages: Fetch messages from a chat.
• Send Message: Reply in an existing chat.
• Start Chat: Open a new conversation with a phone number.
• Get Chat: Retrieve conversation details.

Instagram

Instagram support spans five skills covering DMs, comments, prospect discovery, publishing, and analytics. DMs run over Unipile; comments, discovery, publishing, and analytics use the official Meta Graph API on the instagram gateway.

• Instagram DM: list chats, read messages, send message, start chat, get chat, get profile (resolve an @handle to a provider id).
• Instagram Comments: list recent media, list comments on a post, reply to a comment: the engagement loop.
• Instagram Discovery: get account info, get account media, search hashtag: qualify public Business/Creator prospects against your ICP.
• Instagram Publish: publish a post, carousel (2–10 images), reel, or 24-hour story to a Business/Creator account.
• Instagram Analytics: pull per-post reach, saves, shares, comments, likes, and plays to feed a virality-improvement loop.

Facebook Messenger

Send and receive Facebook Messenger messages through a connected account.

• List Chats: Browse recent Messenger conversations.
• Read Messages: Fetch messages from a chat.
• Send Message: Reply in an existing chat.
• Start Chat: Open a new conversation with a Facebook user.
• Get Chat: Retrieve conversation details.

Gmail

• Read Inbox: Read recent inbox messages.
• Search: Search emails by query string.
• Get Message: Read a specific email by ID.
• Send: Compose and send an email from the connected account.
• Reply: Reply to an existing email thread.
• Create Draft: Save a draft email.
• Send Draft: Send a previously created draft.
• List Labels: List all Gmail labels.
• Modify Labels: Add or remove labels on a message.
• Trash: Move a message to trash.
• Mark Read: Mark a message as read or unread.

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 Info: Retrieve file metadata by ID.
• Create Folder: Create a new folder.
• Create Document: Create a new Google Docs document.
• Create Spreadsheet: Create a new Google Sheets spreadsheet.
• Upload Text: Upload text content as a Drive file.
• Download Text: Download a file's text content.
• Move File: Move a file to a different folder.
• Copy File: Create a copy of a file.
• Rename File: Rename a file.
• Trash File: Move a file to trash.
• Share File: Share a file with users or groups.
• List Permissions: View a file's sharing permissions.

ClickUp

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

Jira

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

Attio

Read and write your Attio CRM: 24 actions spanning records, lists, tasks, notes, threads, comments, meetings, call recordings, and files.

• Records: list objects, list/search/get records, create and update records.
• Lists: list lists, list entries, add a record to a list.
• Tasks: list, create, and complete tasks.
• Notes: create, list, and get notes.
• Threads & comments: list threads, get a thread, create a comment.
• Meetings & recordings: list meetings, list and get call recordings.
• Files & members: list and get files, list workspace members.

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.
• Follow: Follow a user.
• Search: Search recent tweets by query.
• Get User: Look up a user by username.
• Get Tweet: Get a tweet by ID.
• Get User Tweets: List a user's recent tweets.

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.
• Enrich Organization: Get full firmographic details for a company.

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.
• Find Leads: Search leads across campaigns by email or status.
• 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:

• Get Spaces: List spaces in a workspace.
• Get Folders: Retrieve folders in a space.
• Get Lists: List the lists in a space or folder.
• Get Members: List members who can be assigned.
• Get Tasks: List tasks in a list.
• Create Task: Create a task in any list.
• Create Subtask: Create a subtask under a parent task.
• Add Checklist: Add a checklist to a task.
• Add Dependency: Link a task dependency.
• Update Task: Modify task properties.
• Create Plan: Create multiple tasks at once from a plan.

Design & Web

Skills for turning ideas into polished, shippable interfaces:

• ui-ux-pro-max: Generate a complete, non-generic design system (UI style, hex palette, font pairing, layout pattern, anti-patterns, pre-delivery checklist) for any UI you are about to build. Pairs with web-artifacts-builder.
• web-artifacts-builder: Build multi-component web artifacts with React, Tailwind, and shadcn/ui, bundled into a single HTML file.
• theme-factory: Style artifacts with 10 pre-set color/font themes (slides, docs, reports, landing pages) or generate a custom theme.

Media Generation

Generate images, video, and audio the OAgent can attach to its replies or publish directly to a connected channel:

• gemini-image-gen: Text-to-image and image-to-image with Google Nano Banana (Gemini image models), with native aspect-ratio control.
• video-gen-veo: Short videos (Reels, TikToks, ad clips) with Google Veo 3, text-to-video and image-to-video.
• text-to-speech: Convert text to an MP3 with gTTS (free, no API key). Also available as a core skill.

Marketing & Sales

A large family of role-based playbook skills encode expert marketing and sales workflows. Representative marketing ids include marketing-seo-specialist, marketing-growth-hacker, marketing-linkedin-content-creator, and marketing-tiktok-strategist (17 in the marketing-* family). The sales side adds ids like sales-outbound-strategist, sales-pipeline-analyst, and the sdr-* batch skills for research and outreach.

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 OAgent.

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 OAgent. 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 OAgent 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-OAgent 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 OAgent 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.