AI Skills

Backstage publishes a set of curated AI skills — self-contained guidance files that teach an AI coding assistant how to perform common Backstage engineering tasks. Skills are published to a well-known endpoint on backstage.io and can be installed into your repository with the skills.sh tool.

Installing Skills

You need Node.js to run npx.

npx skills add https://backstage.io

This command reads the published index from https://backstage.io/.well-known/skills/index.json and allows you to select which of the available skills you want to install into your repository.

Where skills are installed

skills.sh copies skill files into your repository under a directory it manages (typically .github/skills/ or a similar location depending on your configuration). Refer to the skills.sh documentation for details on target paths and how to customize them.

After installation, you can modify the installed files to adapt them to your project's conventions. Subsequent updates from npx skills add will offer to merge upstream changes.

Using Skills with Your AI Assistant

Once a skill is installed in your repository, attach or reference the relevant SKILL.md file when starting a task with your AI coding assistant. Most AI assistants in editors such as VS Code will automatically pick up instruction files that are committed to your repository.

For example, when migrating MUI imports in a plugin, include the mui-to-bui-migration skill so the assistant follows the correct component mapping and import patterns.

Contributing New Skills

Skills are authored in the Backstage monorepo at docs/.well-known/skills/. Each skill lives in its own subdirectory and must include a SKILL.md file as the primary entry point.

Skill directory layout

docs/.well-known/skills/
  index.json                        # Published index of all skills
  <skill-name>/
    SKILL.md                        # Primary skill entry point (required)
    <optional-supporting-files>

Writing a SKILL.md

A SKILL.md file must include a YAML front matter block with the following fields:

---
name: <skill-name>
description: <short description used in the published index>
---

# Skill Title

Introductory paragraph explaining when and why to use this skill.

...

The name must match the directory name. The description is shown to users when they browse or install skills and should be one to two sentences describing the task the skill covers.

Keep skills focused on a single, well-defined task. A skill that tries to cover too many scenarios is harder to use effectively. Prefer concrete, step-by-step guidance, working code examples, and explicit notes about common pitfalls.

Registering the skill in the index

Add an entry to docs/.well-known/skills/index.json:

{
  "skills": [
    {
      "name": "<skill-name>",
      "description": "<same description as in SKILL.md front matter>",
      "files": ["SKILL.md"]
    }
  ]
}

If your skill includes additional supporting files, list each one in the files array.

Review process

All changes to skills go through the standard Backstage pull request process. When authoring or reviewing a skill, consider:

• Accuracy — Does the skill reflect current Backstage APIs and conventions?
• Completeness — Does it cover the most common cases a developer will encounter?
• Safety — Does it avoid patterns that could introduce security or correctness issues?
• Scope — Is the skill focused on a single task, or should it be split?

Skills are part of the published Backstage documentation surface, so they follow the same contribution guidelines as the rest of the docs. See CONTRIBUTING.md for the full contribution process.