Skip to content

Your First Skill

Prerequisites

If you haven't already, check out our Neon AI Software Development Kit Overview.

This walkthrough assumes you:

  • have some basic knowledge of Python programming,
  • have an account on Github.com, and
  • have a working version of Neon, either on a Mark 2 or a development setup.

Understand the flow of your Skill

It's a good idea to start by writing down how your Skill will work, including

  • What words will the User speak to activate the Skill?
  • What will Neon speak in response?
  • What data will you need to deliver the Skill?
  • Will you need any additional packages or dependencies?

Making a flowchart of events may help you visualize and plan. This could be as simple as drawing one on a sheet of paper. There are also many tools for it available online, some of them are free & some even integrate with your coding. Here is an article that compares several free flowchart tools: https://www.softwaretestinghelp.com/flowchart-software/ which you may find a helpful place to start.

Once you've given these some thought, you can get started.

Basic skill repository structure

Neon maintains a Neon skill template repository at https://github.com/NeonGeckoCom/template-skill. You can visit this page and select Use this template > Create a new repository from the GitHub UI to start with a basic skill setup.

Once the skill repository has been created changing the name can be tricky, so think through the naming convention early. Typically, it should follow this format:

skill-<skill_name>, with the setup.py and manifest.json files appending the name of your user or organization to the skill name. For example, you may see skills such as skill-free_music_archive.neongeckocom or skill-plex.d-mcknight in your Neon device once the skill is installed.

After creating a new repository from the template, clone it to your local development environment. Let's take a closer look at the structure:

.
├── .github/workflows
│   ├── license_tests.yml
│   ├── propose_release.yml
│   ├── publish_release.yml
│   ├── publish_test_build.yml
│   ├── push_skill_json.yml
│   ├── skill_tests.yml
│   └── update_skill_json.md
├── test
│   ├── test_intents.yml
│   ├── test_resources.yml
│   └── test_skill.md
├── .gitignore
├── CHANGELOG.md
├── LICENSE.md
├── README.md
├── __init__.py
├── requirements.txt
├── setup.py
├── skill.json
└── version.py

.github/workflows

Neon's standard GitHub Actions workflows. For more information on what each one does and how it works, please see the documentation on skill testing.

test

All your skill's unit tests should go here. Additionally, this is where the files are for Neon's standard GitHub Actions tests. For details on setting those up, please see the files themselves or the documentation on skill testing.

.gitignore

Files that should not be committed to git. As a general rule, binaries, large files, packaged files (usually in a dist or build folder), and IDE settings should not be committed to a shared git repository. For a list of examples .gitignore files, please see https://github.com/github/gitignore or search https://github.com/NeonGeckoCom for "skill"

CHANGELOG.md

Auto-generated by Neon GitHub Actions workflows. No need to edit manually.

LICENSE.md

Neon is built on components that are mostly using the BSD-2 or BSD-3 license, favoring the BSD-3 license. A full explanation of the legalities of open-source licenses is out of scope of this document, but please read the license file carefully and follow its instructions if you plan to change your skill to use a different license. For legal advice in your country/jurisdiction, please seek an attorney.

The copyright for Neon AI in this file may be safely removed if you are not developing on behalf of Neon AI directly.

README.md

The README file that will appear not just on your GitHub repository main page, but also become the README for any skills published to pypi.org. Follow the template and fill in with the information you came up with in the "Understanding your skill" section above. Be sure to keep this up to date as you add features to your skill.

__init__.py

The primary Python file for your skill. In standard Python development, the presence of this file in a folder marks that the folder is a Python module. In Neon skill development, historically the Skill class itself goes in here, and for simple skills all of the skill code belongs here.

Note that putting the __init__.py file in the root of the repository has fallen out of favor in modern Python development practice. However, to maintain compatibility with older Mycroft skills and installation methods, Neon recommends following the structure outlined in this template repo.

The copyright for Neon AI in this file may be safely removed if you are not developing on behalf of Neon AI directly.

requirements.txt

Third-party Python package requirements, such as requests or libraries for accessing any software you are integrating with Neon. Specifying only a name will cause pip to search pypi.org and pull the latest version.

Generally, it is considered good software practice to pin your versions in a requirements.txt file. For more information on pinning, please see the linked cheatsheet.

setup.py

The file responsible for packaging your skill in a format that can be installed with pip, either by publishing to pypi.org or installing directly via GitHub. This file must be edited before it will work as expected!! Be sure to review the TODO: items in the code, as well as all sections passed to the setup() function at the end of the file, and update them as appropriate for your skill.

Note that the find_resource_files() function in this file can sometimes fail if you do not have certain directories it is searching for (locale, ui, vocab, dialog, regex, res). If this happens to you, you may safely remove the directories you are not using in your skill. Please be aware that doing so will mean important files in those directories will not be packaged with your skill if you add them later - Neon recommends removing these folders at the end of your skill development so you do not forget to add them back in later.

The copyright for Neon AI in this file may be safely removed if you are not developing on behalf of Neon AI directly.

skill.json

Required file for Neon skills to load properly, but it is automatically generated if you use Neon's default GitHub Actions workflows. Neon recommends you use these workflows, which means you can safely ignore any manual edits to this file.

version.py

Tracks your skill version. Neon follows OVOS in using Semantic Versioning and recommends skill developers do the same.

The copyright for Neon AI in this file may be safely removed if you are not developing on behalf of Neon AI directly.