| name | backstage-catalog |
| description | Register a kickstart-generated or adopted repo in a Backstage software catalog using the deterministic `kickstart export backstage` verb, then fill in the human judgment fields. Use when asked to add a scaffolded or adopted project to Backstage. |
Backstage Catalog Registration
Use When
Use this skill when asked to add a kickstart-generated (or adopted) repo to a
Backstage catalog. The mechanical mapping is owned by the deterministic verb —
never hand-derive it; this skill supplies the judgment the verb deliberately
does not.
Procedure
- Run
kickstart export backstage <repo>. It derives catalog-info.yaml
from .kickstart/scaffold.json: derived fields (apiVersion, kind,
metadata name/tags/techdocs annotation, and for systems the System entity
plus child Components) sit inside # kickstart:begin/end fences and
refresh on every run; spec.type, spec.lifecycle: experimental, and
spec.owner: group:default/unknown are emitted once as anonymous
defaults and then belong to the user.
- Review the diff. Never overwrite by hand what the verb owns (inside the
fences); never let the verb own what humans decide (outside them). An
existing hand-written
catalog-info.yaml is refused by the verb —
migrate it by moving its human fields outside a fresh export's fences.
- Fill in the judgment fields outside the fences:
spec.owner: ask the user; replace the group:default/unknown
sentinel with the real owning group.spec.lifecycle: keep experimental unless the user states otherwise.metadata.description: add a one-liner if the README gives a better
one than none.
- Validate: the file parses as YAML and every entity has
apiVersion,
kind, metadata.name, spec.type, spec.lifecycle, spec.owner
(the verb warns on missing required lines — resolve warnings before
reporting done).
Rules
- The verb is the source of truth for derived fields; do not guess fields
the scaffold does not state — omit them or ask.
- Keep names DNS-label safe (lowercase alphanumerics and dashes).
- Re-running the export must be a no-op when nothing changed; if it is not,
something edited inside a fence — restore via re-export and move the edit
outside.
Report Back
Report the file path, created/updated/unchanged, the owner and lifecycle
chosen, and any scaffold fields that had no catalog equivalent.
