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

[rohitkrai03]

Why

RHDH is moving toward an agentic SDLC with fullsend — agents triage issues, implement features, and review code autonomously. The coding agent needs Backstage/RHDH patterns that aren't in training data (BUI is new, NFS is evolving, dynamic plugin conventions are tribal knowledge). No Backstage coding skills exist in the open-source ecosystem — the official backstage.io skills cover migrations and instrumentation, not day-to-day feature development.

This skill fills that gap. It's the daily-driver skill for agents working on RHDH plugins — installed into .fullsend/customized/skills/ alongside rhdh-workspace and available to the code agent during implementation. It also helps human developers using Claude Code, Cursor, or any skills-compatible agent.

What it covers

• BUI-first styling — component mapping, CSS variables, Remix icons (too new for training data)
• NFS Blueprints — PageBlueprint, EntityCardBlueprint, alpha exports, NFS-at-root pattern
• RHDH dynamic plugins — default export gotcha, scalprum naming, class name generator
• Dev app setup — both plugin dev mode and full Backstage app with sidebar nav
• Backstage-specific testing — TestApiProvider, renderInTestApp, entity mocking, MSW
• Plugin type decisions — page vs card vs entity tab vs backend module
• Frontend spec guidance — what to include in PRDs/OpenSpec proposals for frontend features
• Version compatibility — RHDH → Backstage version matrix awareness

How it fits into fullsend

# .fullsend/customized/harness/code.yaml
skills:
  - skills/code-implementation    # base fullsend
  - skills/rhdh-workspace         # monorepo navigation
  - skills/rhdh-coding            # Backstage/RHDH patterns (this skill)

Complements ecosystem skills (ui-ux-pro-max, frontend-design, webapp-testing) for generic UI quality, and official backstage.io skills for migration workflows.

Summary

• 9 files, ~1,200 lines
• References verified against real plugin code in rhdh-plugins and community-plugins
• Tested against a real NFS plugin implementation (boost workspace) — feedback incorporated
• Detection script verified against orchestrator and bulk-import plugins

Files

File	Lines	Purpose
SKILL.md	176	Core skill — principles, BUI-first, NFS, RHDH gotchas, sibling + official skill references
references/bui.md	149	BUI component mapping, CSS variables, Remix icons
references/dev-app.md	212	Plugin dev mode + full Backstage app setup
references/nfs.md	155	NFS Blueprints, package exports, compatWrapper
references/frontend-specs.md	86	Frontend spec guidance for PRDs/OpenSpec
references/plugin-types.md	79	Plugin type decision guide
references/rhdh.md	141	RHDH-specific patterns
references/testing.md	122	Backstage test patterns
scripts/detect-rhdh-context.py	163	Plugin context detection

Test plan

• Detection script tested against orchestrator and bulk-import plugins
• Skill tested in Cursor against real NFS plugin implementation (boost workspace)
• Real usage feedback incorporated (dev-app gaps, NavItemBlueprint removal, PageBlueprint title, translation auto-discovery, NFS-at-root pattern)
• Install via npx skills add and verify skill triggers correctly

🤖 Generated with Claude Code

[durandom]

Review

Comprehensive skill capturing Backstage/RHDH plugin development tribal knowledge. This is the kind of content that saves developers hours of debugging.

What's good

• BUI reference (`bui.md`) — the component mapping table (BUI ↔ MUI) with key API differences is exactly what's needed for migration. Calling out `Card`'s discriminated union, `Select`'s onChange signature, and `Table`'s `isRowHeader` requirement prevents real bugs.
• NFS patterns (`nfs.md`) — alpha file structure, PageBlueprint/EntityContentBlueprint patterns, and the package exports section (NFS-at-root vs legacy-at-root vs alpha pattern) addresses a genuine source of confusion.
• Testing reference (`testing.md`) — TestApiProvider patterns, entity context mocking approaches (EntityProvider vs jest.mock), MSW setup, and the SWR cache reset trick are all verified patterns from real plugins.
• Detection script — stdlib-only Python, clean structure, covers all the right signals (backstage role, frontend system, MUI version, extensions, blueprints, route refs, API refs, dynamic plugin status).
• "Before You Commit" checklist — the ordered sequence (`prettier:fix` → `tsc:full` → `build:all` → `test` → `build:api-reports:only`) with "stop on first failure" is practical.

Issues

1. Merge conflicts — this PR has conflicts with main and no CI runs. Needs a rebase before it can be reviewed for merge readiness.

2. Version bump assumes #49 merged. The diff shows 0.6.0 → 0.7.0, meaning this is based on PR #49's branch. If #49 hasn't merged, this can't either. Clarify the dependency chain.

3. `references/bui.md` caveat. The skill says "Always check `node_modules/@backstage/ui/dist/index.d.ts` for actual prop types" — good. But the BUI component list will go stale as BUI evolves. Consider adding a date or BUI version at the top so readers know when it was last verified.

4. `references/nfs.md` — NavItemBlueprint removal note. "NavItemBlueprint was removed" — this is correct for latest Backstage but worth noting which version this changed in, since plugins targeting older RHDH versions may still need it.

5. Ecosystem skills section. Recommending `npx skills add` for third-party skills is useful, but these URLs/repos could go stale. Consider moving this to a separate reference file that's easier to update.

Recommendation

Excellent content. Blocked on rebase (conflicts) and the #49 dependency. Once those are resolved, this is merge-ready.

[durandom]

Review

Solid skill — the BUI component mapping, NFS-at-root documentation, and RHDH gotchas (default export, scalprum naming, class name generator) are exactly the kind of tribal knowledge that saves agent hours. A few issues to address:

Detection script contradicts NFS-at-root docs

detect_frontend_system() and detect_nfs_blueprints() only look for alpha.tsx/alpha.ts to detect NFS. But the PR's own nfs.md update documents the new migration pattern as NFS at root (src/index.ts), with legacy moved to ./legacy.

A plugin using this new pattern (NFS in index.ts, legacy in legacy.ts, no alpha.* file) would be classified as "legacy" by the detection script, and its blueprints would be invisible.

Suggestion: Check package.json exports for ./legacy or scan src/index.ts for createFrontendPlugin to detect the NFS-at-root pattern. detect_nfs_blueprints() should also scan index.ts/plugin.ts when NFS-at-root is detected.

Extension detection regex may miss unnamed extensions

detect_extensions() matches createRoutableExtension(\s*\{[^}]*name:\s*['"](\w+)['"] — requires a name field immediately inside the config object. Extensions without an explicit name property, or with the name set on the wrapping variable rather than in the options, would be silently skipped. Not a blocker but worth noting.

nfs.md: cross-reference migration path

The section now says the ./alpha pattern is "being phased out" but doesn't point to the nfs-migration sibling skill for how to do it. A one-liner like "For migration steps, use the nfs-migration skill" would close the loop.

Positives

• Version bump (0.6.1 → 0.7.0) is correct per AGENTS.md — new skill = minor
• Detection script is stdlib-only Python ✓
• BUI reference table with API gotchas (Card discriminated union, TextField onChange string, Table isRowHeader) — excellent
• NavItemBlueprint version qualification and translation module auto-discovery gap are good additions to nfs.md
• SKILL.md information architecture is well-structured for agent consumption

🤖 Generated with Claude Code