feat: add NFS migration and Backstage upgrade skills

[rohitkrai03]

Fixes

• https://redhat.atlassian.net/browse/RHIDP-14477

Summary

• nfs-migration — Guide and agent skill for migrating RHDH plugins from the legacy Backstage frontend system to the New Frontend System (NFS). Includes reference files for each extension type, before/after examples, gotchas, and verification checklists. All API patterns verified against the Backstage source code and validated by migrating the quay plugin end-to-end.
• backstage-upgrade — Agent skill for upgrading @backstage/* dependencies using backstage-cli versions:bump, with RHDH version alignment, changelog-based breaking change review, and moved package migration. This skill is also used by the NFS migration skill.

Test plan

• pytest — 283 tests pass
• ruff check — clean
• Migrated @backstage-community/plugin-quay using the skill — tsc, build, and all 79 tests pass
• Review guide and skill content for accuracy

🤖 Generated with Claude Code

[schultzp2020]

@rohitkrai03 I think this skill would be better served upstream rather than here. https://github.com/backstage/backstage/tree/master/docs/.well-known/skills

[rohitkrai03]

@rohitkrai03 I think this skill would be better served upstream rather than here. https://github.com/backstage/backstage/tree/master/docs/.well-known/skills

@schultzp2020 This skill also has knowledge about RHDH specific extensions and blueprints that were converted from old dynamic plugin mount points to NFS APIs. It was created based on the idea that we would need to provide some kind of a guide to customers that they can use to learn about NFS migration and a skill that can help with that migration.

I can create a generic one suited for upstream but I can see its already there - https://github.com/backstage/backstage/blob/master/docs/.well-known/skills/plugin-new-frontend-system-support/SKILL.md.

[christoph-jerolimov]

/cc @durandom @christoph-jerolimov

[schultzp2020]

@rohitkrai03 I think this skill would be better served upstream rather than here. https://github.com/backstage/backstage/tree/master/docs/.well-known/skills

@schultzp2020 This skill also has knowledge about RHDH specific extensions and blueprints that were converted from old dynamic plugin mount points to NFS APIs. It was created based on the idea that we would need to provide some kind of a guide to customers that they can use to learn about NFS migration and a skill that can help with that migration.

I can create a generic one suited for upstream but I can see its already there - https://github.com/backstage/backstage/blob/master/docs/.well-known/skills/plugin-new-frontend-system-support/SKILL.md.

Can you create a PR to update the generic one with the new findings you have here?

[rohitkrai03]

@rohitkrai03 I think this skill would be better served upstream rather than here. https://github.com/backstage/backstage/tree/master/docs/.well-known/skills

@schultzp2020 This skill also has knowledge about RHDH specific extensions and blueprints that were converted from old dynamic plugin mount points to NFS APIs. It was created based on the idea that we would need to provide some kind of a guide to customers that they can use to learn about NFS migration and a skill that can help with that migration.
I can create a generic one suited for upstream but I can see its already there - https://github.com/backstage/backstage/blob/master/docs/.well-known/skills/plugin-new-frontend-system-support/SKILL.md.

Can you create a PR to update the generic one with the new findings you have here?

@schultzp2020 You mean including RHDH specific references?

[schultzp2020]

@rohitkrai03 I think this skill would be better served upstream rather than here. https://github.com/backstage/backstage/tree/master/docs/.well-known/skills

@schultzp2020 This skill also has knowledge about RHDH specific extensions and blueprints that were converted from old dynamic plugin mount points to NFS APIs. It was created based on the idea that we would need to provide some kind of a guide to customers that they can use to learn about NFS migration and a skill that can help with that migration.
I can create a generic one suited for upstream but I can see its already there - https://github.com/backstage/backstage/blob/master/docs/.well-known/skills/plugin-new-frontend-system-support/SKILL.md.

Can you create a PR to update the generic one with the new findings you have here?

@schultzp2020 You mean including RHDH specific references?

No, just the Backstage specific ones.

[durandom]

Review: NFS Migration & Backstage Upgrade Skills

High-quality skill content — the NFS migration guide (docs/nfs-migration-guide.md) is genuinely excellent. Real PR references, gotcha lists, before/after examples, RHDH-specific extensions (drawer, header, homepage). This is the kind of knowledge that's hard to find in one place.

What's good

• Comprehensive reference material — 12 reference files, 3 before/after examples, real migration PRs from rhdh-plugins. The mount-point mapping table alone saves hours of digging.
• Composable design — backstage-upgrade can be called standalone or chained from nfs-migration. The cross-skill references are clean.
• Follows existing skill patterns — intake → routing → workflow → references structure matches other skills in the repo.
• Validated against a real plugin — the quay migration is a strong signal that the patterns work end-to-end.

Blocking

1. Version bump goes backward — see inline comment on pyproject.toml

Non-blocking suggestions

2. No tests — the PR description claims "283 tests pass" but adds zero test files for either skill. Existing skills in this repo have structural tests under tests/unit/. Since these are pure markdown skills with no scripts, this may be intentional — but worth clarifying.
3. NFS migration guide duplicates skill reference content — docs/nfs-migration-guide.md (482 lines) overlaps significantly with the skill's reference files (api-changes.md, gotchas.md, migrate-page.md). This creates a maintenance burden — changes to one must be reflected in the other. Consider making the guide the authoritative human-readable source and having the skill reference files link to it (or vice versa), rather than duplicating content.
4. See inline comments for minor consistency issues.