> ## Documentation Index
> Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

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:

```markdown theme={"theme":{"light":"github-light","dark":"dracula"}}
---
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.