Skip to main content
Welcome to the OpenHome Abilities community! We’re excited to have you here. Whether you’re building a simple utility or a complex interactive experience, this guide will help you get your contribution merged and available on the Marketplace.

​
Community vs Official Abilities

OpenHome Abilities are organized into two categories:

Community Abilities

Created and maintained by contributors like you. Submitted to community/ folder and marked with an orange badge.

Official Abilities

Maintained by the OpenHome team. Located in official/ folder with a blue badge and priority Marketplace placement.
You submit all contributions to the community/ folder. Exceptional community abilities can be promoted to official status over time based on usage and quality.

​
The Quick Version

If you just want to get started right away:
1

Fork the repo

Fork the abilities repository on GitHub
2

Copy a template

Copy templates/basic-template/ to community/your-ability-name/
3

Build your ability

Edit main.py and create your README.md
4

Test it

Upload to the OpenHome Live Editor
5

Submit a PR

Open a Pull Request against the dev branch
That’s it! We’ll review and merge it.

​
Repository Structure

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.
Only submit to the community/ folder. The official/ folder is maintained exclusively by the OpenHome team.

​
Contribution Process Overview

Here’s what happens from idea to merged PR:
  1. Fork and branch - Create your feature branch from dev (not main)
  2. Build - Copy a template and implement your ability
  3. Test - Upload to the Live Editor and verify all paths work
  4. Submit PR - Open a pull request targeting the dev branch
  5. Automated checks - Validation, path checks, security scans, and linting run automatically
  6. Code review - A maintainer reviews (typically 3-5 business days)
  7. Merge to dev - Once approved, your PR is merged to dev
  8. Promotion to main - Maintainers periodically validate and merge dev to main
  9. Marketplace - Your ability becomes available to all users
You don’t need to do anything after your PR is merged to dev. The maintainers handle the dev → main promotion.

​
Branching Strategy

We use a simplified Git Flow model: 
ability/your-ability-name  →  dev  →  main
BranchPurposeWho Merges
mainStable, production-ready. Always deployable.Maintainers only
devIntegration and testing. All PRs target this branch.Maintainers after review
ability/* or add-*Your working branch for a single ability or 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 with a request to re-open against dev.

​
Detailed Guides

Ready to dive deeper? Check out these detailed guides:

Submission Guide

Step-by-step walkthrough from fork to PR

Review Checklist

What your PR needs to pass review

Promotion Path

How community abilities become official

Building Great Abilities

Best practices for high-impact abilities

​
Getting Help

Stuck? We’re here to help:

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

Build docs developers (and LLMs) love

Get started for freeTalk to us