feat: add rhdh-coding skill for Backstage/RHDH plugin development

Adds a coding skill that teaches agents non-obvious Backstage and RHDH
patterns — the knowledge you'd gain after six months of getting burned
by conventions that aren't in the docs or training data.

Covers: BUI-first styling, NFS Blueprints, RHDH dynamic plugin gotchas,
plugin type decisions, Backstage-specific testing, dev app setup (both
plugin dev mode and full Backstage app), and frontend spec guidance for
PRDs/OpenSpec workflows.

References are verified against real plugin code in rhdh-plugins and
community-plugins. Designed to be the daily-driver skill for agents
working on existing plugins — complementary to create-plugin (new
plugins), nfs-migration (migration), and official backstage.io skills.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: Rohit Rai <rohitkrai03@gmail.com>

Author: rohitkrai03

.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Orchestrator skill for RHDH plugin development - onboard, update, and maintain plugins in the Extensions Catalog",
-    "version": "0.6.0"
+    "version": "0.7.0"
   },
   "plugins": [
     {
       "name": "rhdh",
       "source": "./",
       "description": "Skills for RHDH plugin lifecycle management",
-      "version": "0.6.0",
+      "version": "0.7.0",
       "strict": true
     }
   ]

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "rhdh",
   "description": "All-in-one toolkit for Red Hat Developer Hub (RHDH). Covers plugin development, overlay management, environment setup, version compatibility, CI/CD, and RHDH ecosystem navigation.",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "author": {
     "name": "RHDH Store Manager"
   },

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "rhdh-skill"
-version = "0.6.0"
+version = "0.7.0"
 description = "Claude Code skill for RHDH plugin development"
 readme = "README.md"
 license = "Apache-2.0"

skills/rhdh-coding/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: rhdh-coding
+description: >-
+  Backstage and RHDH plugin development patterns. Use when writing, modifying,
+  or reviewing code in a Backstage or RHDH plugin — frontend components, backend
+  services, API clients, styling, testing, entity pages, scaffolder actions,
+  catalog processors, NFS Blueprints, dynamic plugin configuration. Also use
+  when asked to "add a feature to a plugin", "implement a Backstage component",
+  "create an API client", "write plugin tests", "add a backend route", "create
+  a scaffolder action", "what plugin type should I use", or any coding task in
+  a Backstage or RHDH codebase.
+---
+
+# RHDH Coding
+
+Patterns for Backstage and RHDH plugin development that agents need but can't
+reliably get from training data or codebase discovery alone. This covers what
+you'd learn after six months of getting burned by non-obvious conventions.
+
+## Before You Write Code
+
+### 1. Check for existing specs
+
+Look for a spec, PRD, or OpenSpec design for this work — in `docs/plans/**/`,
+`specifications/`, `openspec/changes/*/`, or linked from the issue. If found,
+use the component list and acceptance criteria as your implementation blueprint.
+Read `references/frontend-specs.md` for what good frontend specs include.
+
+### 2. Discover the plugin context
+
+Run the detection script to understand what you're working with:
+
+```bash
+python scripts/detect-rhdh-context.py --path <plugin-dir>
+```
+
+This reports: Backstage role, frontend system (legacy/NFS/dual), existing
+extensions, MUI version, dynamic plugin status, plugin ID, scalprum name.
+
+### 3. Read workspace instructions
+
+```bash
+test -f AGENTS.md && cat AGENTS.md
+test -f CLAUDE.md && cat CLAUDE.md
+```
+
+These contain repo-specific rules that override general patterns.
+
+### 4. Check version compatibility
+
+Consult `../rhdh/references/versions.md` for the RHDH → Backstage version
+matrix. Your `@backstage/*` dependency versions must match the target RHDH
+version. Mismatched versions cause runtime errors — most commonly "Cannot
+read properties of undefined."
+
+## Styling: BUI First
+
+**For new plugins,** use Backstage UI (`@backstage/ui`) with CSS Modules and
+BUI CSS variables. **In existing plugins,** match whatever the workspace already
+uses — if it's MUI v4, stay consistent rather than mixing libraries. Only
+introduce BUI in a workspace that has already adopted it or is actively migrating.
+
+**Priority for new plugins:**
+1. **BUI** (`@backstage/ui`) — default for new plugins and new workspaces
+2. **MUI v5** (`@mui/material`) — when BUI lacks the component you need
+3. **MUI v4** (`@material-ui/core`) — legacy maintenance only
+
+When using MUI v5 alongside BUI, add the class name generator to prevent
+collisions in dynamic plugin bundles:
+
+```typescript
+// src/index.ts
+import { unstable_ClassNameGenerator as ClassNameGenerator } from '@mui/material/className';
+ClassNameGenerator.configure(name => name.startsWith('v5-') ? name : `v5-${name}`);
+```
+
+**Icons:** Use `@remixicon/react` (not `@material-ui/icons`).
+
+Read `references/bui.md` for the component mapping table and CSS variable reference.
+
+## Frontend System: NFS for New Plugins
+
+New plugins targeting RHDH 1.5+ should use the **new frontend system (NFS)**
+with Blueprints (`createFrontendPlugin`, `PageBlueprint`, `EntityCardBlueprint`,
+etc.).
+
+Legacy system (`createPlugin` + `createRoutableExtension`) is for existing
+plugins not yet migrated. For migration, use the `nfs-migration` sibling skill.
+
+Read `references/nfs.md` for Blueprint patterns, alpha export structure, and
+compatWrapper decisions.
+
+## Plugin Types
+
+Not sure whether to build a page, a card, an entity tab, or a backend module?
+Read `references/plugin-types.md` for the decision guide.
+
+## Backend: New System Only
+
+All backend code MUST use:
+- `createBackendPlugin` — new standalone backend capabilities
+- `createBackendModule` — extensions to existing plugins (catalog, scaffolder, auth)
+
+From `@backstage/backend-plugin-api`. Never the legacy backend system.
+
+Core services: `httpRouter`, `logger`, `rootConfig`, `httpAuth`, `database`,
+`scheduler`, `permissions`, `discovery`.
+
+**Default export is required** from the entry point (`src/index.ts`). Missing
+default export is the #1 cause of "plugin not loading" in RHDH.
+
+## RHDH Dynamic Plugins
+
+Key gotchas (read `references/rhdh.md` for full details):
+
+- **Default export required** from `src/index.ts` — missing this is the #1 cause of "plugin not loading"
+- **Scalprum name** must match the key in `dynamic-plugins.yaml` wiring (derived from package name)
+- **MUI v5 class name generator** required when using `@mui/material` in dynamic bundles
+- **Auth:** use `fetchApi` — it includes auth headers automatically. Don't implement custom auth.
+- **RHDH-only Blueprints:** `AppDrawerContentBlueprint`, `GlobalHeaderMenuItemBlueprint` — not upstream
+
+`references/rhdh.md` covers all RHDH-specific patterns including backend modules,
+extension points, theming, i18n, and the common package pattern.
+
+## Analytics
+
+BUI components (`Link`, `ButtonLink`, `Tab`, `MenuItem`, `Tag`, `Table` rows)
+have built-in click analytics via the Backstage Analytics API. Don't add manual
+`captureEvent('click', ...)` for these — it produces duplicates. Use `noTrack`
+prop to suppress the built-in event only when replacing it with a domain-specific
+verb (e.g., `deploy`, `approve`). For detailed instrumentation guidance, install
+the official `plugin-analytics-instrumentation` skill from backstage.io.
+
+## Testing
+
+Backstage has its own test infrastructure that differs from standard React testing.
+Read `references/testing.md` for: TestApiProvider setup, renderInTestApp,
+entity context mocking, async component testing, accessibility testing, and
+common gotchas.
+
+## Reference Index
+
+| Reference | Load when... |
+|-----------|-------------|
+| `references/frontend-specs.md` | Writing specs, PRDs, or OpenSpec proposals for frontend features |
+| `references/bui.md` | Using BUI components — mapping table, CSS variables, icons |
+| `references/plugin-types.md` | Deciding what type of plugin or extension to build |
+| `references/nfs.md` | Writing NFS code — Blueprints, package exports, compatWrapper |
+| `references/dev-app.md` | Plugin dev mode, full Backstage app setup, sidebar, app-config |
+| `references/testing.md` | Writing tests — TestApiProvider, entity mocking, a11y |
+| `references/rhdh.md` | RHDH-specific patterns — dynamic plugins, backend modules, i18n |
+
+## Sibling Skills (rhdh-skill)
+
+| Skill | Use when... |
+|-------|------------|
+| `create-plugin` | Scaffolding a new plugin from scratch |
+| `nfs-migration` | Migrating an existing plugin from legacy to NFS |
+| `overlay` | Managing overlay packaging for the Extensions Catalog |
+| `backstage-upgrade` | Upgrading Backstage dependency versions |
+| `rhdh-local` | Running and testing plugins locally |
+| `rhdh` | RHDH version matrix, repo navigation, ecosystem context |
+
+## Official Backstage Skills (backstage.io)
+
+Install via `npx skills add https://backstage.io`. These are complementary —
+they cover migration and instrumentation workflows that this skill does not.
+
+| Skill | Use when... |
+|-------|------------|
+| `mui-to-bui-migration` | Migrating a plugin from MUI to BUI (component-by-component guide) |
+| `plugin-new-frontend-system-support` | Adding NFS support while keeping legacy working (dual entry point) |
+| `plugin-full-frontend-system-migration` | Fully migrating a plugin to NFS, dropping legacy |
+| `app-frontend-system-migration` | Migrating an entire Backstage app to the new frontend system |
+| `plugin-analytics-instrumentation` | Adding analytics events via Backstage Analytics API |
+| `onboard-to-openapi-server` | Migrating backend router to typed OpenAPI tooling |

skills/rhdh-coding/references/bui.md

@@ -0,0 +1,149 @@
+# Backstage UI (BUI) Reference
+
+Setup: `yarn add @backstage/ui @remixicon/react` and add `import '@backstage/ui/css/styles.css'` to `src/index.ts`.
+
+BUI uses **CSS Modules** with CSS custom properties — not makeStyles or CSS-in-JS.
+
+```css
+/* MyComponent.module.css */
+@layer components {
+  .container {
+    padding: var(--bui-space-4);
+    background-color: var(--bui-bg-surface-1);
+    border-radius: var(--bui-radius-2);
+  }
+}
+```
+
+```tsx
+import { Box, Text } from '@backstage/ui';
+import styles from './MyComponent.module.css';
+
+export const MyComponent = () => (
+  <Box className={styles.container}>
+    <Text variant="title-small">Title</Text>
+  </Box>
+);
+```
+
+## Component Mapping
+
+| BUI | Replaces MUI | Key differences |
+|-----|-------------|-----------------|
+| `Text` | `Typography` | `variant`: title-large/medium/small/x-small, body-large/medium/small/x-small. `weight`, `truncate` props. |
+| `Button` | `Button` | `variant="primary"/"secondary"/"tertiary"`, `isDisabled`, `destructive`, `loading` |
+| `ButtonIcon` | `IconButton` | `icon={<RiIcon />}`, `onPress` (not `onClick`), needs `aria-label` |
+| `Card` + `CardHeader/Body/Footer` | `Paper`, `Card` | Composition pattern |
+| `Flex` | `Box display="flex"` | `direction`, `align`, `justify="between"` (not `"space-between"`) |
+| `Grid.Root` + `Grid.Item` | `Grid container/item` | `columns={{ sm: '12' }}`, `colSpan={{ sm: '12', md: '6' }}` |
+| `TextField` | `TextField` | `isRequired`, `onChange` receives string directly (not event!) |
+| `PasswordField` | — | Password input with show/hide toggle |
+| `Dialog` + `DialogTrigger` | `Dialog` | Trigger pattern |
+| `Tabs` + `TabList/Tab/TabPanel` | `Tabs/TabList/TabPanel` | `defaultSelectedKey`, id-based |
+| `Menu` + `MenuTrigger/MenuItem` | `Menu/Popover` | Trigger pattern. Also: `MenuSection`, `MenuSeparator`, `SubmenuTrigger` |
+| `Tooltip` + `TooltipTrigger` | `Tooltip` | Both imported from `@backstage/ui` |
+| `Tag` | `Chip` | Direct replacement |
+| `TagGroup` | — | Grouped tags |
+| `Select` | `Select` | Single and multiple selection modes |
+| `Switch` | `Switch` | Toggle |
+| `Checkbox` | `Checkbox` | Checkbox input |
+| `CheckboxGroup` | — | Grouped checkboxes with shared label, `orientation`, `isRequired` |
+| `RadioGroup` + `Radio` | `RadioGroup` | BUI pattern |
+| `SearchField` | `InputBase` | Search input |
+| `SearchAutocomplete` | — | Search with autocomplete popover (`SearchAutocompleteItem`) |
+| `Skeleton` | `Skeleton` | Loading placeholder |
+| `Accordion` + `AccordionTrigger/Panel` | `Accordion` | Trigger pattern. `AccordionGroup` for multiple. |
+| `Alert` | `@material-ui/lab Alert` | `status`, `title`, `description` props |
+| `Badge` | — | Inline badge/label with optional icon |
+| `DateRangePicker` | — | Date range input field |
+| `FieldLabel` | — | Form field label with description and secondary label |
+| `Header` | — | Page header with breadcrumbs and tabs |
+| `PluginHeader` | — | Plugin-level header (used by NFS PageLayout automatically) |
+| `List` + `ListRow` | `List/ListItem` | BUI list pattern |
+| `Slider` | — | Range slider input |
+| `Table` + `useTable` | `Table` | Data tables with `useTable` hook (supports `complete`, `offset`, `cursor` pagination) |
+| `TablePagination` | — | Standalone pagination component |
+| `FullPage` | — | Full-page layout wrapper |
+| `Container` | — | Centered content container with max-width |
+| `VisuallyHidden` | — | Accessibility helper |
+
+## Icons
+
+Use `@remixicon/react` — not `@material-ui/icons`.
+
+```tsx
+import { RiSearchLine, RiCloseLine } from '@remixicon/react';
+<RiSearchLine size={16} />
+```
+
+| MUI Icon | Remix Icon |
+|----------|------------|
+| Close | RiCloseLine |
+| Search | RiSearchLine |
+| Settings | RiSettingsLine |
+| Add | RiAddLine |
+| Delete | RiDeleteBinLine |
+| Edit | RiEditLine |
+| Check | RiCheckLine |
+| Error | RiErrorWarningLine |
+| Warning | RiAlertLine |
+| Info | RiInformationLine |
+| ExpandMore | RiArrowDownSLine |
+| ChevronRight | RiArrowRightSLine |
+| Menu | RiMenuLine |
+| MoreVert | RiMore2Line |
+| Visibility | RiEyeLine |
+
+Full catalog: https://remixicon.com/
+
+## CSS Variables
+
+| Category | Variables |
+|----------|----------|
+| Spacing | `--bui-space-1` (4px) … `--bui-space-8` (32px) |
+| Foreground | `--bui-fg-primary`, `--bui-fg-secondary`, `--bui-fg-link`, `--bui-fg-danger` |
+| Background | `--bui-bg-surface-0` (page), `--bui-bg-surface-1` (card), `--bui-bg-hover`, `--bui-bg-solid` |
+| Border | `--bui-border`, `--bui-ring` |
+| Radius | `--bui-radius-2`, `--bui-radius-3`, `--bui-radius-full` |
+| Typography | `--bui-font-regular`, `--bui-font-size-1/2/3`, `--bui-font-weight-regular/bold` |
+
+## MUI Spacing → BUI Spacing
+
+| `theme.spacing(n)` | BUI variable |
+|--------------------|-------------|
+| `theme.spacing(0.5)` | `var(--bui-space-1)` |
+| `theme.spacing(1)` | `var(--bui-space-2)` |
+| `theme.spacing(2)` | `var(--bui-space-4)` |
+| `theme.spacing(3)` | `var(--bui-space-6)` |
+| `theme.spacing(4)` | `var(--bui-space-8)` |
+
+## MUI Colors → BUI Colors
+
+| `theme.palette.*` | BUI variable |
+|-------------------|-------------|
+| `text.primary` | `var(--bui-fg-primary)` |
+| `text.secondary` | `var(--bui-fg-secondary)` |
+| `background.paper` | `var(--bui-bg-surface-1)` |
+| `background.default` | `var(--bui-bg-surface-0)` |
+| `error.main` | `var(--bui-fg-danger)` |
+| `divider` | `var(--bui-border)` |
+
+## Responsive
+
+```tsx
+import { useBreakpoint } from '@backstage/ui';
+const breakpoint = useBreakpoint(); // 'sm' | 'md' | 'lg' | 'xl'
+```
+
+## Known Limitations
+
+BUI does not yet have: Timeline, Pagination, Alert, Autocomplete.
+Use MUI v5 (`@mui/material`) for these — add the class name generator when mixing.
+
+Some Backstage APIs (e.g., NavItemBlueprint `icon` prop) expect MUI `IconComponent`
+type. Remix icons aren't type-compatible — use MUI icons for these specific cases.
+
+## Further Reference
+
+- BUI docs: https://ui.backstage.io
+- Full migration guide: `mui-to-bui-migration` skill in community-plugins