Skill README.md

The README.md file in each Skill repository is used to provide an overview of the Skill and its functionality.

This file is used by the Skills Marketplace to display the appropriate information including the Card view and Details view.

When creating your Skill, the Mycroft Skills Kit will automatically generate your first README.md for you. Alternatively you can use the Skills Meta Editor to generate a compatible README.md and ensure all the relevant information is included.

Top tips for a great README

  • The title should not include the word Skill

  • There is limited space on the Skill Card in the Marketplace. Try to keep Skill titles, one-line descriptions and intent examples clear and concise. Longer strings of text will be truncated (cut off). Try to keep:

    • Titles under 22 characters

    • One-line descriptions under 50 characters

    • First example under 40 characters (this will be shown on the Card view and should make sense as a single phrase)

    • All other examples under 50 characters

  • Note: The one-line description is the text between the Skill title and the "About" section.

  • The primary category, being the category in bold, is where the Skill will be displayed in the Marketplace by default.

Suggesting changes to an existing README

A GitHub account is required to submit changes; please register for an account now if necessary. Then head to the Skill's GitHub repository (repo) to get started. You can always find a link to a Skill's repo in the Marketplace. Simply click on the Skill, and look for a GitHub link on the right.

Edit and make a pull request (PR)

This is the simplest and most direct method for Skill Authors if you have a clear idea of what changes need to be made.

README.md files are written using the Markdown syntax, which is a way to style text on the web. If you aren't familiar with Markdown formatting, GitHub has an excellent 3 minute guide to get you started.

How to

1. Edit the file

  • Select the README.md file

  • Then the pencil icon to edit the file

2. Review your changes using the Skills Meta Editor

  • GitHub provides the preview tab for quickly checking your formatting. However, in the Mycroft Marketplace, there are several ways a Skill might be shown.

  • Copy and paste the file contents into the README.md tab of the Meta Editor to see a preview of the Card and Detail views.

  • Please be aware that after importing text into this tool, it may be modified to fit the standard features of a Mycroft Skill's README.

3. Propose the changes

  • At the bottom of the edit page on GitHub will be a short "Propose file change" form. Submitting this form will automatically create a fork of the repo in your account, as well as a pull request to the main project.

  • This provides the Skill Author with a list of any proposed changes, as well as the message you include in this form.

  • Please try to be clear and concise in your message as to what has been changed and why. Be aware that we have developers from across the world, and English may not be their first language.

Create a new 'issue'

This is the best option if you are unsure about what the final text should look like.

How to

1. Create a 'new issue'

  • From the Skills GitHub repo, select the 'Issues' tab

  • Then the green 'New issue' button on the right.

2. Write a clear and concise issue message

  • The title of an issue should be a very brief overview of the changes you are suggesting. If the changes are limited to a specific section or for a particular reason, say that here. An example might be, "Suggested changes to description for readability".

  • In the main comment area, please detail the changes you are suggesting, and try to be descriptive about which section you are referring to. Instead of "there's a typo in skill", we might write "In the first intent example there is a typo, skill should be skill."

  • If you are proposing multiple changes, consider grouping them under headings.

  • If you are proposing a block of text, consider using the 'quote' formatting to highlight it.

3. Preview and Submit

  • Just underneath the title field is a 'Preview' tab. This lets you check the formatting of your message.

  • Once you're happy, hit submit.

PreviousCombined TemplateNextFAQ

Last updated