Building a Skill

A Skill bundles tools, credentials, and knowledge into a reusable package that can be assigned to agents. Unlike Apps, Skills don't require an external adapter service — they wire together existing tools with the context agents need to use them effectively.

When a Skill is Enough

You don't need an App (adapter) if:

• The tools already exist as built-in engine tools (web search, file operations, shell, git, HTTP requests)
• The tools come from an existing MCP server you've already connected
• The integration only needs a simple API key passed to built-in tools like http_request
• The tools are ToolFactory tools (Python source code executed at runtime, no adapter needed)

In these cases, a Skill is all you need — it bundles the right tools, wires the credential, and provides agents with knowledge on how to use them.

Examples

Skill	Tools Used	Why No App
Research the Web	web_search, web_scrape, http_request	Built-in engine tools
Review Code	read_file, search_code, git_diff	Built-in engine tools
Send Mail	send_email	Built-in engine tool, just needs SMTP credential
Bannerbear	bannerbear_* tools	ToolFactory tools (Python source compiled at runtime)

Manifest Format

Skills are registered through the Developer Portal, just like Apps. Your manifest declares the skill definition without an adapter URL:

{
  "schema_version": "1.0",
  "name": "My Research Skill",
  "description": "Agents can research topics using web search and scraping.",
  "icon": "magnifying-glass",
  "category": "research",

  "capabilities": [],

  "credentials": [
    {
      "key": "SEARCH_API_KEY",
      "type": "api_key",
      "label": "Search API Key"
    }
  ],

  "skill": {
    "name": "Research the Web",
    "description": "Research topics using web search and page scraping.",
    "knowledge": "You can research topics on the web. Use web_search to find information via search engines. Use web_scrape to read specific pages in detail. Use http_request for direct API calls when you have a URL. Verify facts from multiple sources. Summarize findings clearly with source attribution.",
    "tool_names": ["web_search", "web_scrape", "http_request"]
  },

  "setup_instructions": [
    "Get a Search API key from your search provider",
    "Enter the API key when prompted during installation",
    "Assign the skill to your agents in the Team Builder"
  ]
}

Key Differences from App Manifests

Field	App	Skill-only
Adapter URL	Required (hosts the service)	Not needed (no adapter)
capabilities	["send"], ["receive"], etc.	Always []
skill.tool_names	Usually [] (auto-discovered from MCP)	Lists specific built-in or ToolFactory tool names
mcp_auth	Often needed (for adapter calls)	Rarely needed

Writing Good Knowledge

The knowledge field is injected verbatim into the agent's context whenever this skill is assigned. It's the single most important field in a skill definition.

Do

• List every tool by name — agents need to know exactly what's available
• Describe when to use each tool — not just what it does, but when to pick it over alternatives
• Include behavioral guidance — rate limits, best practices, formatting preferences
• Keep it concise — this goes into the LLM context window for every request

Don't

• Don't repeat tool descriptions — the tool's own description field handles that
• Don't include examples with product-specific names — use generic topics (animals, geography, science)
• Don't write novel-length instructions — every token costs money and context space

Example: Good Knowledge

You can research topics on the web. Use web_search to find information via search
engines. Use web_scrape to read specific pages in detail. Use http_request for
direct API calls when you have a URL. Verify facts from multiple sources. Summarize
findings clearly with source attribution. Prefer primary sources.

Example: Bad Knowledge

This skill allows you to search the web. You have tools available.
Please use them wisely and follow best practices.

The bad example doesn't name any tools, doesn't explain when to use which, and gives no actionable guidance.

Auto-Created Skills

Skills can also be auto-created when you install an App or connect an MCP server. In both cases, the Skill stays in sync with its source — tool discovery updates the Skill's tool list automatically.

From Apps

When an App manifest includes a skill definition, installing the App auto-creates a linked Skill. This Skill gets its tools from the App's MCP tool discovery. You don't need to list tool names manually — they're discovered from the adapter.

From MCP Servers

When you connect a standalone MCP server (Settings > MCP Servers), ORQO auto-creates a linked Skill that bundles the server's discovered tools. No manifest or Developer Portal submission needed — the MCP server connection is enough.

Registering in the Developer Portal

1. Sign in to the Developer Portal with your Google or GitHub account
2. Navigate to the Skills section (/developer/skills)
3. Click + New Skill
4. Enter a URL that serves your manifest.json
5. ORQO fetches the manifest and shows a preview
6. Review and confirm to create a draft listing
7. The detail page opens at /developer/skills/:slug with all parsed manifest sections
8. Click Submit for Review when ready

For skill-only integrations without an adapter, you can host the manifest.json on any static file host or your own server. The URL only needs to be reachable during registration and manifest refresh — it doesn't need to handle runtime traffic.

Checklist

Before submitting a new Skill:

• manifest.json has schema_version and name
• skill.tool_names lists only tools that actually exist (built-in engine tools, ToolFactory tools, or tools from a connected MCP server)
• skill.knowledge names every tool and explains when to use each one
• credentials lists all required credentials (omit if none needed)
• description is a single clear sentence
• category matches an existing category
• setup_instructions are specific and actionable
• No product-specific names in knowledge text (use generic examples)