spotlight_skill
The spotlight_skill resource, and the skill resource of the API: a folder of
files, a SKILL.md with instructions and any files beside it, that a station
gives its runs in skills.
| Kind | Endpoint | Terraform | Address |
|---|---|---|---|
skill | /api/resources/teams/{teamId}/skills | spotlight_skill | <team key>/<key> |
See Resource API for the operations, headers and errors every kind shares.
Example
resource "spotlight_skill" "core_grafana" {
team_id = spotlight_team.core.id
key = "grafana"
files = {
"SKILL.md" = file("${path.module}/skills/core/grafana/SKILL.md")
"queries/latency.promql" = file("${path.module}/skills/core/grafana/queries/latency.promql")
}
}skills/core/grafana/SKILL.md:
---
name: grafana
description: Look up dashboards
---
Search before you guess.A station gives it with skills = [spotlight_skill.core_grafana.key], or
"skills": ["grafana"] in JSON.
Fields
| Field | Type | Default | Description |
|---|---|---|---|
key | string | required | What stations give the skill by. Lowercase words joined by dashes, at most 64 characters. Must not start with spotlight-. Fixed: an update that changes it is refused; Terraform replaces the resource. |
files | map of name to string | required | Each file's text by its path within the skill's folder. Must hold SKILL.md. |
A read also returns these fields, taken from the SKILL.md frontmatter.
| Field | Type | Default | Description |
|---|---|---|---|
description | string | read-only | The frontmatter's description. |
secrets | array of objects | read-only | Each { name, description } from the frontmatter's secrets. |
tools | array of strings | read-only | The frontmatter's tools. |
SKILL.md
SKILL.md opens with YAML frontmatter between two --- lines, followed by the
skill's instructions.
| Key | Type | Default | Description |
|---|---|---|---|
name | string | required | Must equal the skill's key. |
description | string | required | When to use the skill. Must not be empty. |
tools | array of strings | [] | Tools the skill uses, each a tool name, usually <integration>.<tool> as in grafana.search. |
secrets | map of name to string | {} | Secrets the skill needs: each secret name, matching ^[A-Z][A-Z0-9_]{0,63}$, with what it is for. |
The body after the frontmatter must not be empty.
Files
- A path is relative to the skill's folder, as in
queries/latency.promql: no leading/, no\or NUL character, and no empty,.or..part. - A skill holds at most 50 files.
- A skill's files hold at most 524,288 characters together.
What a station gives
A station's skills names team skills by key and catalog skills as
catalog.<name>@<x.y.z>. Where a station gives a skill:
- The run also gets every tool in a team skill's
tools. - A team skill whose
secretsname any secret the workspace does not hold is not given. - A catalog skill is given only if the workspace's plan includes it, and brings the catalog tools it uses.
A station may not name a skill starting spotlight-. See
Built-in tools and skills for the
skills Spotlight gives itself and the catalog skills.
Where a run finds its skills
Each skill given to a run is laid out as a folder in the run's workspace; see
Inside a sandbox. The folder is named for the skill's key; a
catalog skill's folder is spotlight-catalog-<name>.
| Harness | Folder | Found by |
|---|---|---|
claude-code | .claude/skills/<folder>/ | the harness, as its own skills |
cursor | .spotlight/skills/<folder>/ | the task briefing, which lists each skill's SKILL.md path and description |
codex | .spotlight/skills/<folder>/ | the task briefing, which lists each skill's SKILL.md path and description |
Before the run starts, anything else in that skills folder is removed.
Delete
A delete is refused with 409 in-use while any station gives the skill.