skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
vinzscam/backstage-skills52 installs

using-backstage-catalog

Use when a Backstage plugin needs to interact with the catalog — fetching one entity by ref, querying entities with filters, or registering/unregistering catalog locations. Triggers on imports of catalogApiRef from @backstage/plugin-catalog-react, or @backstage/catalog-client in backend code.

How do I install this agent skill?

npx skills add https://github.com/vinzscam/backstage-skills --skill using-backstage-catalog
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill provides standard development patterns for interacting with the Backstage Catalog. It is safe in its implementation but identifies a potential vulnerability surface for indirect prompt injection, as it demonstrates how to ingest user-contributed data from catalog entities without explicit sanitization or boundary markers.

  • Socketpass

    No alerts

  • Snykpass

    Risk: LOW · No issues

What does this agent skill do?

Backstage Catalog Patterns

When to use this skill

  • Plugin needs to fetch a specific entity by its ref (e.g. a Group, Component, or User)
  • Plugin needs to query entities with filters (e.g. all Components owned by a team, all Groups of a given type)
  • Plugin needs to register a new catalog location, refresh an entity, or unregister one programmatically
  • This applies to both frontend and backend code; the entry points differ but the operations are the same

Choose the right pattern

Frontend (in a frontend plugin component)

SituationPatternReference
Fetch one entity by refuseApi(catalogApiRef).getEntityByRef(ref)references/fetch-by-ref.md (Frontend section)
Query entities with filtersuseApi(catalogApiRef).getEntities({ filter })references/query-entities.md (Frontend section)
Register / refresh / unregister a locationuseApi(catalogApiRef).addLocation / refreshEntity / removeLocationByIdreferences/register-entity.md (Frontend section)

Backend (in a backend plugin or module)

SituationPatternReference
Fetch one entity by refcatalog.getEntityByRef(ref, { credentials }) via catalogServiceRefreferences/fetch-by-ref.md (Backend section)
Query entities with filterscatalog.getEntities({ filter }, { credentials }) via catalogServiceRefreferences/query-entities.md (Backend section)
Register / refresh / unregister a locationcatalog.addLocation / refreshEntity / removeLocationById via catalogServiceRefreferences/register-entity.md (Backend section)

Two invocation modes

  • Standalone (mid-development): user is editing an existing plugin. Pick the right reference based on the situation table above and apply.
  • Post-scaffold (called by creating-backstage-plugin): apply the pattern to a freshly scaffolded plugin. Each reference's "Post-scaffold usage" section names the file and insertion point — frontend-template scaffolds use the Frontend pattern, backend-template scaffolds use the Backend pattern.

Common gotchas

  • In frontend code, catalogApiRef comes from @backstage/plugin-catalog-react, NOT @backstage/catalog-client. The latter is for backend.
  • useApi itself comes from @backstage/frontend-plugin-api in NFS plugins; catalogApiRef is plugin-specific and stays in @backstage/plugin-catalog-react.
  • In backend code, depend on catalogServiceRef from @backstage/plugin-catalog-node — it wraps the catalog client with auth/discovery wiring already done and takes BackstageCredentials directly. Methods take { credentials } (a BackstageCredentials object), not { token } (a string). For incoming HTTP requests, get credentials via httpAuth.credentials(req). For service-to-service work (scheduled tasks, init-time fetches), use auth.getOwnServiceCredentials(). Don't manually new CatalogClient(...) — that's the underlying API but the service ref is the canonical surface.
  • getEntityByRef returns Entity | undefined. Always handle the undefined case (entity may have been deleted or the ref may be malformed).
  • getEntities returns { items: Entity[] } — destructure or access .items.
  • Filters on getEntities are AND-combined within an object, OR-combined across an array of objects.
  • Frontend: don't fetch in a render — wrap in useAsync (auto-fetch on mount/dep change) or useAsyncFn (button-triggered fetch) from react-use. Don't manually wire useState for { loading, error, data } — the hook handles race conditions and unmount cleanup correctly.
  • Backend: don't fetch on every HTTP request without caching — for hot paths, use coreServices.cache to memoize results that don't need to be live.

UI conventions

Use @backstage/ui for rendering when possible (Skeleton, Alert, Text, Flex, Button, …). See using-backstage-ui skill for the full component catalog and styling guidance.

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/vinzscam/backstage-skills/using-backstage-catalog">View using-backstage-catalog on skillZs</a>