Contributing an Ability

Thanks for wanting to contribute! Once you’ve built and tested your Ability in the OpenHome Live Editor, this guide walks you through downloading it and submitting it to the community repo as a pull request.

Source on GitHub

The canonical CONTRIBUTING.md in the abilities repo. This page mirrors it, so refer to the GitHub copy if anything looks out of date.

Branching & Merging Strategy

We use a simplified Git Flow. All contributions follow this flow:

ability/your-ability-name  →  dev  →  main

Branch	Purpose	Who merges
`main`	Stable, production-ready. Always deployable.	Maintainers only
`dev`	Integration and testing. All PRs target this.	Maintainers after review
`ability/`, `add-`	Your working branch for a single ability/change.	You push, maintainers merge to `dev`

Never open a PR directly to main. All PRs must target dev. PRs targeting main will be closed and you’ll be asked to re-open against dev.

How the Repo Is Organized

official/    ← Maintained by OpenHome. Don't submit PRs here.
community/   ← Your contributions go here.
templates/   ← Starting points. Copy one to get going.
docs/        ← Guides and API reference.

You submit to community/ only. Exceptional community abilities can be promoted to official over time.

Step-by-Step Guide

1. Fork the Repo

Go to openhome-dev/abilities and click Fork in the top-right corner. This creates your own copy of the repo under your GitHub account, the copy you’ll push your changes to.

2. Clone Your Fork

Clone your fork, then point it at the upstream repo so you can stay in sync:

git clone https://github.com/YOUR_USERNAME/abilities.git   # use your fork's repo name (keeping "abilities" is recommended)
cd abilities
git remote add upstream https://github.com/openhome-dev/abilities.git
git fetch upstream
git checkout dev
git pull upstream dev

3. Create Your Ability Branch

Branch off dev, not main:

git checkout -b add-your-ability-name dev   # e.g. git checkout -b add-dad-jokes dev

Use a descriptive branch name like add-dad-jokes, add-pomodoro-timer, or fix-weather-error-handling.

4. Add Your Ability

Once your Ability is finalized and tested in the Live Editor:

In the Live Editor, create a commit of your Ability.
Download it with the Download button at the bottom-left of the Live Editor. This saves your Ability as a zip file.
Unzip the file, then place the Ability folder inside the community/ folder of your cloned repo, so it lives at community/your-ability-name/. You can move it with your file explorer, or from the repo root:

mv path/to/your-ability-name community/

The folder name under community/ becomes your ability’s name. Use lowercase, hyphenated names (for example, dad-jokes), not underscores or spaces.

5. Sync with `dev` Before Submitting

dev is under active development, so pull the latest changes into your branch before opening your PR to avoid conflicts:

git fetch upstream
git merge upstream/dev

6. Submit Your PR

Commit your ability and push it to your fork:

git add community/your-ability-name/
git commit -m "Add your-ability-name community ability"
git push origin add-your-ability-name

Open a Pull Request on GitHub:

Base branch: dev (not main)
Compare branch: add-your-ability-name
Fill out the PR template completely

What Happens After You Open a PR

Automated checks run: validate-ability, path-check, security-scan, and linting must all pass.
A maintainer reviews: typically within 3–5 business days.
Feedback round: push additional commits to the same branch, and the PR updates automatically.
Merge to dev: once approved, a maintainer squash-merges your PR into dev.
Promotion to main: periodically, maintainers validate dev and merge it into main. Your ability becomes available on the Marketplace at that point.

Review Checklist

Before opening your PR, make sure:

PR targets the dev branch (not main)
Files are in community/your-ability-name/ (not in official/)
README.md is present with a description, suggested trigger words, and setup instructions
No hardcoded API keys (use "YOUR_API_KEY_HERE" placeholders)

What NOT to Do

Don’t	Do instead
Open a PR to `main`	Target `dev`: always
Branch off `main`	Branch off `dev`
Submit to `official/`	Submit to `community/`
Use `print()`	Use `self.worker.editor_logging_handler.info()`
Use `asyncio.sleep()`	Use `self.worker.session_tasks.sleep()`
Use `asyncio.create_task()`	Use `self.worker.session_tasks.create()`
Hardcode API keys	Use placeholders + document in README
Forget `resume_normal_flow()`	Call it on every exit path
Write long spoken responses	Keep it short: 1-2 sentences per `speak()` call
Push directly to `dev` or `main`	Push to your ability branch, open a PR

Promotion Path

Community abilities that stand out can be promoted to Official status:

Criteria	Threshold
Marketplace installs	50+
Stability	No critical bugs for 30+ days
Code quality	Clean, follows SDK patterns
Author responsiveness	Responds to issues
Usefulness	Fills a real gap

When promoted, the ability moves from community/ to official/, gets the Official badge on Marketplace, and OpenHome takes over maintenance (author stays credited).

Getting Help

Discord

Ask questions and share works-in-progress with the community.

Report a Bug

Found a bug in an ability? Open an issue.

Suggest an Ability

Vote on and suggest new ability ideas in Discussions.

SDK Reference

Full SDK docs for ability authors.

License

By submitting a PR, you agree that your contribution is licensed under the MIT License. Original authorship is always credited in your ability’s README and in CONTRIBUTORS.md.

Source on GitHub

​Branching & Merging Strategy

​How the Repo Is Organized

​Step-by-Step Guide

​1. Fork the Repo

​2. Clone Your Fork

​3. Create Your Ability Branch

​4. Add Your Ability

​5. Sync with dev Before Submitting

​6. Submit Your PR

​What Happens After You Open a PR

​Review Checklist

​What NOT to Do

​Promotion Path

​Getting Help

Discord

Report a Bug

Suggest an Ability

SDK Reference

​License

Branching & Merging Strategy

How the Repo Is Organized

Step-by-Step Guide

1. Fork the Repo

2. Clone Your Fork

3. Create Your Ability Branch

4. Add Your Ability

5. Sync with `dev` Before Submitting

6. Submit Your PR

What Happens After You Open a PR

Review Checklist

What NOT to Do

Promotion Path

Getting Help

License