abilities

<a id="top"></a>

<h1 align="center">OpenHome Abilities</h1>

<h3 align="center">Open-source voice-AI plugins that give your OpenHome Agent new powers.</h3>

Build, share, and remix.

Build an Agent plugin in Python  ·  🎙️ Test it with voice  ·  🛍️ Ship your Agent Skill to the Marketplace

<br />

<table align="center">
<tr>
<td width="420" valign="top">
⭐ &nbsp;<a href="#official-abilities"><b>Official OpenHome Abilities</b></a><br />
_{Team-maintained Abilities. Tested, stable, and supported.}
</td>
<td width="420" valign="top">
🧰 &nbsp;<a href="#templates"><b>Abilities Starter Templates</b></a><br />
_{Minimal, working scaffolds to copy and build on.}
</td>
</tr>
<tr>
<td width="420" valign="top">
🌍 &nbsp;<a href="#community"><b>Community Contributed Abilities</b></a><br />
_{Voice Abilities built and shared by the community.}
</td>
<td width="420" valign="top">
🤝 &nbsp;<a href="#contributing"><b>Contribution Guide</b></a><br />
_{Build your own Ability and open a pull request.}
</td>
</tr>
</table>

<a id="what-are-abilities"></a>

🧩 What Are Abilities?

An Ability is a plugin that extends your OpenHome Agent to do something the language model cannot do from a prompt alone, such as fetching data from the web, controlling a smart device, playing audio, remembering things across sessions, or running a multi-step voice workflow.

The test: if the LLM can already answer it in conversation, it is not adding value as an Ability.

You speak a trigger word  ->  your Ability is triggered  ->  its flow runs  ->  the Agent responds

You write the logic. OpenHome handles speech-to-text, the LLM, text-to-speech, and routing. Most Abilities are a single file: main.py.

<a id="quick-reference"></a>

📖 Quick Reference

New to OpenHome? Here is the vocabulary in one place.

Key terms
| Term | What it means |
|------|---------------|
| Agent (Personality) | The voice assistant itself: an LLM, a voice, and a prompt. Every OpenHome speaker runs one, and it adapts to you as you talk. |
| Ability | A Python plugin that gives an Agent a new power (this repo). |
| Trigger words | The spoken phrases that activate an Ability, set in the dashboard. |
| CapabilityWorker | The SDK object an Ability uses for all input and output (speak, listen, call the LLM, store files). |
| Marketplace | Where the community shares Agents and Abilities: build in the dashboard, request to publish, and others install and review. |
| DevKit | OpenHome's hardware (a Raspberry Pi) that Local Abilities run on. |

The four Ability types
| Type | Triggered by | Lifecycle | Used for | Entry file(s) |
|------|--------------|-----------|----------|---------------|
| 🟦 Skill | A user trigger word | Runs once, then exits | Hotword-triggered tasks (the original pattern) | main.py |
| 🟪 Agent Controlled | The Agent decides | Runs on demand | Data lookups, tool use, delegated actions | main.py (In active development) |
| 🟧 Background Daemon | Auto-starts when a session begins | Loops until the session ends | Monitoring, alarms, ambient intelligence | background.py |
| 🟩 Local | A user trigger word | Runs on DevKit hardware | GPIO, sensors, and other on-device hardware | main.py + devkit_functions.py |

<a id="build"></a>

🚀 Build Your First Ability

You only need to edit one file. Here is the whole loop.

1. Pick a template

git clone https://github.com/openhome-dev/abilities.git
cp -r abilities/templates/basic-template my-first-ability

2. Edit main.py (this is a complete, working Ability)

from src.agent.capability import MatchingCapability
from src.main import AgentWorker
from src.agent.capability_worker import CapabilityWorker

class MyFirstCapability(MatchingCapability):
    worker: AgentWorker = None
    capability_worker: CapabilityWorker = None

    #{{register capability}}          # required boilerplate, copy exactly

    def call(self, worker: AgentWorker):
        self.worker = worker
        self.capability_worker = CapabilityWorker(self)
        self.worker.session_tasks.create(self.run())

    async def run(self):
        await self.capability_worker.speak("Hi! What's on your mind?")
        user_input = await self.capability_worker.user_response()
        reply = self.capability_worker.text_to_text_response(
            f"Give a short, helpful response to: {user_input}"
        )
        await self.capability_worker.speak(reply)
        self.capability_worker.resume_normal_flow()   # always call this on exit

Two rules that matter most: keep the #{{register capability}} tag exactly as written, and call resume_normal_flow() on every exit path or the speaker stays silent. OpenHome manages the platform-level config.json at runtime, so you never create or edit it.

3. Upload it

• Zip your folder.
• Go to app.openhome.com, then Abilities, then Add Custom Ability.
• Upload the zip.

4. Set your trigger words in the dashboard (the phrases that activate your Ability).

5. Test it in the Live Editor, then say a trigger word in a conversation.

Prefer the terminal? Once you are comfortable, the OpenHome CLI does this whole loop (create, voice-test, push) without zipping or uploading by hand.

📖 Full walkthrough: docs/getting-started.md

<a id="templates"></a>

🧰 Abilities Starter Templates

Do not start from a blank file. Each template is a minimal, working scaffold for one Ability type; together they cover all four types, so you can start from the pattern closest to what you are building. Copy one and build on top of it.

🟦 Skill (runs once on a trigger word)
| Template | Teaches | Entry |
|----------|---------|-------|
| Basic Template | The minimal Speak, Listen, Respond, Exit loop | main.py |
| API Template | Fetch from an external API and speak the result | main.py |
| Loop Template | Multi-turn conversation until an exit phrase | main.py |
| Slack Assistant | Slack by voice: channels, messages, DMs, and people search | main.py |
| Send Email | Send email with attachments via send_email() | main.py |
| Read Write File | Persist data across sessions with file storage | main.py |
| OpenClaw | Drive a local computer through OpenClaw | main.py |
| OpenHome Local Link | Turn speech into shell commands on a local machine | main.py |
| Smart Home | Voice-control MQTT smart-home devices, an LLM picks the device and command | main.py |
| Alarm | A Skill and a daemon working together via shared files | main.py + background.py |

🟪 Agent Controlled (the Agent decides when to run it, still in development)
| Template | Teaches | Entry |
|----------|---------|-------|
| Wikipedia | Answer "what is" questions with a short Wikipedia summary, no key needed | main.py |

🟧 Background Daemon (auto-runs and loops for the whole session)
| Template | Teaches | Entry |
|----------|---------|-------|
| Background Daemon | A continuous monitor loop | background.py |

🟩 Local (runs on real DevKit hardware)
| Template | Teaches | Entry |
|----------|---------|-------|
| Philips Hue Light Control | Control a Hue bulb over Bluetooth, no bridge needed | main.py + devkit_functions.py |
| DevKit LED Lights Control | Voice-control the DevKit's onboard NeoPixel ring | main.py + devkit_functions.py |
| Camera Feed | Look at the DevKit's live camera feed and answer questions about it | main.py + devkit_functions.py |
| DevKit Stats | Report live DevKit telemetry by voice: CPU, memory, temperature, uptime | main.py + devkit_functions.py |

More detail on each template: templates/README.md

<a id="official-abilities"></a>

⭐ Official OpenHome Abilities

Maintained by the OpenHome team. Tested, stable, and supported. Install any of these from the dashboard, or read the source to learn the patterns.

Trigger words are set in the dashboard when you install an Ability, not in the code.

<a id="community"></a>

🌍 Community Contributed Abilities

Built by the community and featured on the Marketplace. Each Ability is reviewed for security and SDK compliance before it is merged.

Browse all community Abilities →

Want yours featured here? See the Contribution Guide.

<a id="cli"></a>

⌨️ OpenHome CLI

Once you are comfortable, the openhome CLI runs the whole build loop from your terminal: create, voice-test, push, and contribute, with no zipping or manual uploads.

Setup (from the repo root)

python3 -m venv cli/.venv && source cli/.venv/bin/activate
pip install -e cli
cp .env.example .env          # add your OPENHOME_API_KEY (Settings, then API Keys)

Your API key alone is enough (sent as X-API-KEY), and openhome then runs from anywhere. For openhome call you also need an audio player: on macOS brew install mpv portaudio, on Linux sudo apt install mpv portaudio19-dev.

The loop

openhome agents                               # list your agents
openhome create my-skill -t basic-template    # scaffold into user/ and push to your account
#   ...edit user/my-skill/main.py...
openhome push user/my-skill --commit -m "v2"  # update the ability in place, commit a version
openhome call                                 # real mic and speaker voice test
openhome sync                                 # pull your account's abilities back into user/
openhome delete my-skill                      # remove from account and local folder

Contribute from the CLI. Your personal Abilities live in user/ (gitignored). Promote a finished one into community/ and open a PR:

openhome push_to_community my-skill           # copy user/my-skill into community/, then validate

Full command reference and the API contract: cli/README.md.

<a id="contributing"></a>

🤝 Contribution Guide

We welcome community Abilities. The short version:

1. Fork this repo.
2. Copy a template into community/your-ability-name/.
3. Build your Ability (main.py plus README.md).
4. Validate it: python3 validate_ability.py community/your-ability-name.
5. Open a Pull Request against the dev branch.

First time? Look for good-first-issue. Full guide: CONTRIBUTING.md. Also: CODE_OF_CONDUCT.md, SECURITY.md.

<a id="contributors"></a>

🌟 Contributors

Built by an incredible community. Thank you to everyone who has shipped an Ability or improved the project.

Want to contribute? Start here.

🏆 Community to Official

Exceptional community Abilities can be promoted to Official status. We look for:

• Stability, no critical bugs for 30 or more days.
• Quality, clean code and great voice UX.
• Maintenance, a responsive author.

When promoted, the Ability moves to official/, gets the official badge on the Marketplace, and the author is credited permanently. Learn more.

<a id="documentation"></a>

📚 Official OpenHome Docs

Get started

• Getting Started, your first Ability in 5 minutes
• Patterns Cookbook, common patterns with code

SDK reference

• OpenHome SDK Reference, the complete SDK (source of truth)
• CapabilityWorker, the I/O object every Ability uses

Design and advanced

• What Makes a Good Ability
• Designing OpenHome Abilities
• Agent Memory and Context Injection
  Ship it
• Publishing to Marketplace
• Promotion Path

📜 License

Licensed under the MIT License. All contributions to community/ are licensed under the same terms. By submitting a PR you agree to these terms, and original authorship is always credited.

Back to top