Skill Settings

Have you ever wanted to store settings for a Skill locally to a Device? For instance, you might want the User to specify a preference the first time they use a Skill, and then store that preference fo

Skill Settings provide this ability.

They are a simple extension of the Python dict that enables local storage of settings. Skill settings can be accessed from the


class. Skill settings can also interact with a backend system to provide a graphical user interface (GUI) for Skills configuration. Skills configuration is done through metadata described in an optional

settingsmeta.json or settingsmeta.yaml file.

How do I use Skill Settings?

Skill Settings inherit from a Python dict. This means that you can use it just like you would any other Python dictionary.

print(self.settings.get('meaning of life')) # outputs None... oh.. :(
self.settings['meaning of life'] = 42
print(self.settings.get('meaning of life')) # outputs 42! yay

More information on Skill Settings




file is created at the root level of the Skill's directory. The file is created when a Skill uses the Skill Settings feature.

Here is an example directory listing of a Skill that has a



4 drwxr-xr-x 4 mycroft mycroft 4096 Nov 24 14:34 .
4 drwxrwxrwx 38 mycroft mycroft 4096 Nov 27 12:50 ..
4 drwxr-xr-x 3 mycroft mycroft 4096 Nov 23 16:57 dialog
4 drwxr-xr-x 8 mycroft mycroft 4096 Nov 27 12:36 .git
4 -rw-r--r-- 1 mycroft mycroft 20 Nov 23 16:57 .gitignore
8 -rw-r--r-- 1 mycroft mycroft 6265 Nov 23 16:57
8 -rw-r--r-- 1 mycroft mycroft 7509 Nov 24 14:34 init.pyc
12 -rw-r--r-- 1 mycroft mycroft 11357 Nov 23 16:57 LICENSE
4 -rw-r--r-- 1 mycroft mycroft 695 Nov 24 14:33
4 -rw-r--r-- 1 mycroft mycroft 35 Nov 25 19:28 settings.json

NOTE: The Skill directory should be owned by user mycroft and have group ownership of mycroft with file system permissions as shown above - that is, all files should have permissions 644 and all directories should have permission 755.

When a Skill is shut down - which usually happens when restarting a service, or reloading a Skill - it will create a settings.json file and store the dict data there. When a Skill loads, it reads the settings.json file and loads the settings into the Skill. Knowing this makes it easier to build and test Skills, because you can create the settings.json file first with settings in it, and use these in your Skills development, and then add in code later on that writes to settings.json.

Web configurable Settings with settingsmeta file

For some Skills, the User may need to configure them before they are usable. Examples include Skills where an API token or login is required.

This functionality is provided by the settingsmeta file. This file defines settings and their values that the User can configure on Mycroft will automatically synchronize the settings.json file with the settings that the User can configure on

To use this feature, you need to have a settingsmeta.json or settingsmeta.yaml file in the root directory of the Skill. The settingsmeta file must follow a specific structure.

Below is a JSON example of this structure from the pianobar-skill. You can see the code for this Skill - it has excellent example on how to use web configurable Skill Settings.

"skillMetadata": {
"sections": [
"name": "Login",
"fields": [
"name": "email",
"type": "email",
"label": "Email",
"value": ""
"name": "password",
"type": "password",
"label": "Password",
"value": ""

Here is the same set of settings, as it would be configured with YAML:

- name: Login
- name: email
type: email
label: Email
value: ""
- name: password
type: password
label: Password
value: ""

More information on the settingsmeta file

You may use JSON or YAML to define your settingsmeta file. We recommend YAML, as most people find it easier to work with.

skillMetadata (Object)

An Object containing one or more sections elements.

sections (Array)

An Array containing each of the elements the Settings needs to function.

sections > name (String)

The group name used as a display lable on the Skills page.

sections > fields (Array)

Array of Field Objects. Each Field Object takes four properties:

  • sections > fields > field > name (String)

The name of the field is used by the Skill to set the value of the field. Not defined for field > type = "Label". The generated settings.json file will use this name for the entered data.

  • sections > fields > field > label (String)

Text to be displayed above the data entry box on the Skills page on (or by itself, for field > type = "Label").

  • sections > fields > field > type (Enum)

NOTE: Any combination of uppercase and/or lowercase is acceptable. The data type of this field. The supported types are:

  • Text: (any kind of text)

  • Email: (text validated as an email address)

  • Checkbox: (boolean, True or False)

  • Number: (text validated as a number)

  • Password: (text hidden from view by default)

  • sections > fields > field > value (String)

Optional The initial value for the field.

  • sections > fields > field > placeholder (String)

Optional Placeholder text to show before data is entered in the field (or possibly as a tooltip)