Skills - Spotify for Backstage

A skill is a multi-file instruction set that equips an AI agent with capabilities, typically specialized knowledge or workflows. While rules are short guidelines, skills are richer. They can include step-by-step procedures, reference files, code templates, and examples.

What makes a good skill

Write a skill when you have a repeatable process that your team does regularly and that has known pitfalls. Skills work best when they are:

Focused: covers one specific workflow, not an entire domain
Actionable: gives the agent concrete steps to follow
Maintainable: small enough that one team can keep it up to date

Good candidates:

“How to create a database migration” (step-by-step with validation checks)
“How to set up a new data pipeline” (template files + configuration)
“How to troubleshoot BigQuery query performance” (diagnostic steps + common fixes)

Poor candidates:

Catch-all skills that try to cover everything about one topic
One-off tasks better served by a prompt

Skill format

A skill is a directory containing a SKILL.md file and optionally other supporting files:

my-skill/
├── SKILL.md           # Main instruction file (required)
├── references/        # Optional reference files
│   ├── schema.md
│   └── examples.md
└── templates/         # Optional code templates
    └── migration.ts

SKILL.md

The SKILL.md file is the entry point. It starts with YAML frontmatter describing the skill’s metadata, followed by the instruction body:

---
name: database-migration-creator
description: Creates database migrations following team conventions
---

# Database Migration Creator

Create database migrations that follow our team's conventions.

## When to use

Use this skill when the user asks to create a new database migration,
add or modify a database table, or change a column.

## Steps

1. Read the existing migrations in `src/migrations/` to understand naming
2. Create a new migration file with the next sequential number
3. Add both `up` and `down` functions
4. Validate foreign key references exist
5. Run the migration locally to verify

SKILL.md frontmatter fields

Field	Required	Description
`name`	Yes	Human-readable name of the skill
`description`	Yes	Short description of what the skill does
`disciplines`	No	Areas of expertise (e.g. `backend`, `web`, `data`)
`categories`	No	Topic areas (e.g. `databases`, `testing`)
`owner`	No	Team that maintains the skill (falls back to CODEOWNERS)
`lifecycle`	No	`experimental`, `production`, or `deprecated` (defaults to `experimental`)
`visibility`	No	`public`, `private`, or `restricted`
`usecases`	No	Specific use cases the skill addresses
`labels`	No	Freeform tags for additional categorization
`dependsOn`	No	Entity refs this skill depends on
`environment`	No	Target environment for the skill
`license`	No	License identifier
`compatibility`	No	Compatibility information
`allowedTools`	No	Tools the skill is allowed to use

Supporting files in the skill directory are loaded into the agent’s context alongside SKILL.md, giving the agent access to templates, schemas, and reference material.

How skills are discovered

Skills are automatically discovered by AI Explorer’s entity providers — no catalog-info.yaml is required. The providers scan configured GitHub organizations for any file named SKILL.md. Metadata is extracted from the SKILL.md frontmatter (name and description are required), and ownership falls back to CODEOWNERS if not specified in the frontmatter. Simply commit a SKILL.md file to any directory in a scanned repository and AI Explorer will pick it up on its next scan.

Optional: catalog-info.yaml override

If a catalog-info.yaml is placed as a sibling to SKILL.md (in the same directory, not at the repo root), it can override the entity metadata. The catalog-info.yaml must define an AiContext entity with apiVersion: spotify.net/v1alpha1. This is an advanced override mechanism — most teams won’t need it.

Browsing skills

In the Portal UI, navigate to AI Explorer and select the Skills tab. You can filter by category, owner, certification status, and marketplace. Click any skill to view its content, metadata, and install instructions.

​What makes a good skill

​Skill format

​SKILL.md

​SKILL.md frontmatter fields

​How skills are discovered

​Optional: catalog-info.yaml override

​Browsing skills