Menu
Common rules for working with this repository
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
How to build UI in this repo — the bui (@backstage/ui) design system vs legacy @backstage/core-components + MUI v4, which to reach for, and how to read Backstage Storybook component/story source. Use when creating or changing pages, cards, layouts, buttons, or any frontend component.
Patterns for implementing tables. Covers the bui Table ('@backstage/ui') — preferred for new, simple tables — and the feature-rich '@backstage/core-components' Table with search, filtering, and column-visibility persistence.
Read, classify, and triage Sentry issues for this Backstage app, propose mitigations, and decide their disposition (fix, resolve, mute, or escalate). Use when given a Sentry issue URL (giantswarm.sentry.io/issues/...), asked to investigate a Sentry error/exception/CSP violation, asked why an image/script/style/font was blocked on a page, or asked to mute/ignore noisy Sentry issues.
Build Backstage backend plugins with createBackendPlugin and core services: DI, httpRouter, secure-by-default auth, Knex DB, routes, testing. Use for APIs and background jobs.
Build Backstage frontend plugins with the new Frontend System: createFrontendPlugin, blueprints, routes, Utility APIs, testing. Use for pages, nav, entity content, or cards.
Create a changeset file for versioning packages. Use when the user wants to document changes for release, create a changelog entry, or bump package versions.
| name | common |
| description | Common rules for working with this repository |
packages/ and plugins in plugins/packages/app - Frontend application (React)packages/backend - Main backend servicepackages/backend-headless-service - Headless backend servicepackages/backend-common - Shared backend utilitiesplugins/gs - Main Giant Swarm frontend plugin (largest plugin with 375+ files)plugins/gs-backend - Backend plugin for GS functionalityplugins/flux & plugins/flux-react - Flux CD integrationplugins/kubernetes-react - Kubernetes utilities and hooksplugins/ui-react - Shared UI component libraryplugins/gs-common - Shared constants and utilitiesauth-backend-module-gs, scaffolder-backend-module-gs, techdocs-backend-module-gs.env file (not checked in)env-cmd for loading environment variablesgithub-app-development-credentials.yaml (not checked in)app-config.local.yaml.example to app-config.local.yamldocs/development.md)certificate.yaml (see certificate.yaml.example)yarn prettier:fix before committing code changes.GSClustersPage, EntityGSDeploymentsContent)use prefix (e.g., useDeploymentStatusDetails, useFluxResources)generateUID, parseDate, toTitleCase)gs, flux-react, kubernetes-react)GS prefix for Giant Swarm customizationsindex.ts, and sometimes testshooks/ subdirectoriesutils/ subdirectories.test.ts or .test.tsx naming conventione2e-tests/ directoriesyarn test - Run testsyarn test:all - Run tests with coverageyarn test:e2e - Run Playwright E2E testscoverage/ directorysetupTests.ts filesyarn lint - Lint changed files since origin/mainyarn lint:all - Lint all filesyarn fix - Auto-fix linting issuesyarn tsc - Type check with incremental modeyarn tsc:full - Full type check without skipping lib checksyarn build:all - Build all packagesyarn build:backend - Build backend onlyyarn build:backend-headless-service - Build headless servicepackages/backend/Dockerfilehelm/backstage/ directory.circleci/config.yml)main; the @giantswarm/backstage-plugin-* packages are published to npm via Changesets (add a .changeset/*.md entry).backstage:^ version specifier (managed by Backstage CLI)patch-package for dependency patches (applied in postinstall)app-config.yaml (base), app-config.local.yaml (local overrides), app-config.production.yaml (production)tsconfig.json extends Backstage CLI config.env, *-credentials.yaml, or certificate.yaml files*.local.yaml files are gitignored