Mycroft AI
  • Documentation
  • About Mycroft AI
    • Why use Mycroft AI?
    • Glossary of terms
    • Contributing
    • FAQ
  • Using Mycroft AI
    • Get Mycroft
      • Mark II
        • Mark II Dev Kit
      • Mark 1
      • Picroft
      • Linux
      • Mac OS and Windows with VirtualBox
      • Docker
      • Android
    • Pairing Your Device
    • Basic Commands
    • Installing New Skills
    • Customizations
      • Configuration Manager
      • mycroft.conf
      • Languages
        • Français (French)
        • Deutsch (German)
      • Using a Custom Wake Word
      • Speech-To-Text
      • Text-To-Speech
    • Troubleshooting
      • General Troubleshooting
      • Audio Troubleshooting
      • Wake Word Troubleshooting
      • Log Files
      • Support Skill
      • Getting more support
  • Skill Development
    • Voice User Interface Design Guidelines
      • What can a Skill do?
      • Design Process
      • Voice Assistant Personas
      • Interactions
        • Intents
        • Statements and Prompts
        • Confirmations
      • Conversations
      • Error Handling
      • Example Interaction Script
      • Prototyping
      • Design to Development
    • Development Setup
      • Python Resources
      • Your First Skill
    • Skill Structure
      • Lifecycle Methods
      • Logging
      • Skill Settings
      • Dependencies
        • Manifest.yml
        • Requirements files
      • Filesystem access
      • Skill API
    • Integration Tests
      • Test Steps
      • Scenario Outlines
      • Test Runner
      • Reviewing the Report
      • Adding Custom Steps
      • Old Test System
    • User interaction
      • Intents
        • Padatious Intents
        • Adapt Intents
      • Statements
      • Prompts
      • Parsing Utterances
      • Confirmations
      • Conversational Context
      • Converse
    • Displaying information
      • GUI Framework
      • Show Simple Content
      • Mycroft-GUI on a PC
      • Mark 1 Display
    • Advanced Skill Types
      • Fallback Skill
      • Common Play Framework
      • Common Query Framework
      • Common IoT Framework
    • Mycroft Skills Manager
      • Troubleshooting
    • Marketplace Submission
      • Skills Acceptance Process
        • Information Review Template
        • Code Review Template
        • Functional Review Template
        • Combined Template
      • Skill README.md
    • FAQ
  • Mycroft Technologies
    • Technology Overview
    • Roadmap
    • Mycroft Core
      • MessageBus
      • Message Types
      • Services
        • Enclosure
        • Voice Service
        • Audio Service
        • Skills Service
      • Plugins
        • Audioservice Plugins
        • STT Plugins
        • TTS Plugins
        • Wake Word Plugins
      • Testing
      • Legacy Repo
    • Adapt
      • Adapt Examples
      • Adapt Tutorial
    • Lingua Franca
    • Mimic TTS
      • Mimic 3
      • Mimic 2
      • Mimic 1
      • Mimic Recording Studio
    • Mycroft GUI
      • Remote STT and TTS
    • Mycroft Skills Kit
    • Mycroft Skills Manager
    • Padatious
    • Precise
    • Platforms
Powered by GitBook
On this page
  • Top tips for a great README
  • Suggesting changes to an existing README
  • Edit and make a pull request (PR)
  • Create a new 'issue'

Was this helpful?

  1. Skill Development
  2. Marketplace Submission

Skill README.md

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

PreviousCombined TemplateNextFAQ

Last updated 4 years ago

Was this helpful?

This file is used by the to display the appropriate information including the and .

When creating your Skill, the will automatically generate your first README.md for you. Alternatively you can use the 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.

How to

1. Edit the file

  • Select the README.md file

  • Then the pencil icon to edit the file

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

  • 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

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

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 to get you started.

2. Review your changes using the

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

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

Skills Marketplace
Card view
Details view
Mycroft Skills Kit
Skills Meta Editor
3 minute guide
Skills Meta Editor
Meta Editor
fork
pull request