Building custom skills

OpenEnsemble’s skill-builder lets your coder/coordinator write new skills at runtime. Anything you can call from Node — REST APIs, local hardware integrations, shell commands, your own services — is fair game.

The fastest path

Talk to a coder or coordinator agent and ask for what you want, e.g.:

“Build me a skill that checks my local library’s public RSS feed for new books by my favorite authors. Assign it to my reading assistant.”

The agent will:

1. Read the SKILL_BLUEPRINT.md that ships under skills/.
2. Scaffold a folder under users/{your-id}/skills/{slug}/.
3. Write a manifest.json (name, description, the tool calls).
4. Write execute.mjs (the actual code).
5. Assign the custom skill to the agent you chose so it can use the tools.

Restart-free: the skill is picked up the next time an agent reasons.

The blueprint

skills/SKILL_BLUEPRINT.md is the canonical reference. It’s loaded into the skill-builder’s context whenever it’s writing a skill — your agent reads the same doc.

Assignment, validation, and testing

For a larger idea, Skill Builder can keep a draft with sources, proposed tools, credentials, and unanswered choices. Review it before asking to build. A small, specific edit can update an existing skill directly.

Each custom skill has an assigned agent. Choose it in Settings → Skills → Custom Skills, or name it in your build request. In single-assistant mode, your primary handles the enabled skill set; stored assignments return when you switch back to the ensemble.

The builder checks code, manifest/handler consistency, and eligible smoke-test calls before saving. A validation error should be corrected before relying on the skill. Warnings identify checks that were skipped. User-authored tools are registered from their manifests; you do not edit core TOOL_ALIASES to add one.

Ask the builder to test one tool with explicit arguments using skill_try_tool. That uses the production sandbox and can perform the tool’s real action, so choose a read-only example first. Inspect returned results and the skill log. Code and manifest edits retain up to ten versions; skill_rollback can list and restore a previous version.

For voice use, tell the builder the skill must work from a voice device. Its manifest needs voice_device: true. For a tool that still is not called, use Run Inspector.

Monitored sources and instant phrases

Ask for a tracker with its source, filter, cadence, and delivery preference. The builder can implement the fetch/filter/check/notify sequence; inspect the resulting monitor in Tasks → Monitors. See Tasks & scheduler.

Teach a short phrase for a frequently used tool and manage it through Routines → Saved fast paths. Built-in requests keep their routing priority; a conflicting phrase may use ordinary chat instead.

Custom drawers

A skill can ship its own UI panel, available as an app icon inside Skills in the sidebar (Menu → Skills on mobile). Ask Skill Builder to include a drawer when creating the skill, or to add one to an existing skill. Its icon appears automatically alongside Finance and Tutor; select it to open the panel and use All skills to return to the launcher.

Dashboard widgets

When you ask for an “at-a-glance,” dashboard, card, or tablet view, Skill Builder can add a declarative dashboardWidgets entry to a new or existing custom skill. Each widget is tied to one exact same-skill tool marked readOnly:true. OE renders a bounded summary, metrics, and list—custom skills cannot inject HTML or JavaScript into dashboards.

Because these cards refresh unattended, OE runs their data tools with the skill/user filesystem mounted read-only and native network disabled. A custom widget reads local state; an ordinary user-triggered tool or approved watcher can refresh that state separately. Calendar and Email use OE’s trusted built-in adapters instead.

For an existing skill, ask the agent to update its widget. It can patch the data handler, add or mark the tool read-only with skill_update_tool_def, and add or replace the widget through skill_update_manifest; the skill does not need to be recreated. See Display dashboards in the Guide for adding the resulting card, configuring it, and understanding display-session privacy.

User-scoped vs. system skills

• skills/{slug}/ — system-wide, available to all users (pre-bundled with OE).
• users/{userId}/skills/{slug}/ — visible only to that user, not shared.

Creating a custom skill does not make it available to other accounts. Skill Builder manages user-created skills; bundled system skills are part of the installation.

Editing existing skills

Same agent, just say “edit the {skill} skill to also do X”. The agent will read the current manifest + execute.mjs, propose changes, and apply them.

Removing a skill

Delete the skill folder, or ask the agent to remove it. Owners can also disable a system skill globally in Settings → Skills.