Skip to content

Commit e808bed

Browse files
committed
Fix skill spec compliance and add automation scripts
Review all 7 RHDH skills against the Agent Skills open standard and fix all flagged issues. Metadata and reference fixes: - Fix all frontmatter name fields to lowercase-hyphens - Rewrite descriptions to third person per spec - Fix broken reference paths across overlay workflows - Normalize CLI naming in workflow files - Add missing reference_index entries in rhdh skill - Fix stale hardcoded version tags in env-reference.md - Add missing gotchas to create-frontend-plugin and generate-frontend-wiring New automation scripts (stdlib-only Python per ADR-0002): - rhdh-local: fetch-plugin-metadata.py - create-backend-plugin: scaffold.py - create-frontend-plugin: scaffold.py - overlay: analyze-pr.py, triage-prs.py - export-and-package: export-plugin.py Bug fixes: - Fix Windows path separator inconsistency in sync.py - Skip Unix permission check on Windows in test suite
1 parent 1c5f188 commit e808bed

23 files changed

Lines changed: 3084 additions & 121 deletions

File tree

skills/create-backend-plugin/SKILL.md

Lines changed: 27 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
---
2-
name: RHDH Backend Dynamic Plugin Bootstrap
3-
description: This skill should be used when the user asks to "create RHDH backend plugin", "bootstrap backend dynamic plugin", "create backstage backend plugin for RHDH", "new backend plugin for Red Hat Developer Hub", "create dynamic backend plugin", "scaffold RHDH backend plugin", "new scaffolder action", "create catalog processor", or mentions creating a new backend plugin, backend module, or server-side functionality for Red Hat Developer Hub or RHDH. This skill is specifically for backend plugins - for frontend plugins, use the separate frontend plugin skill.
2+
name: create-backend-plugin
3+
description: Bootstraps a new backend dynamic plugin for Red Hat Developer Hub (RHDH). Use when the user asks to "create RHDH backend plugin", "bootstrap backend dynamic plugin", "create backstage backend plugin for RHDH", "new backend plugin for Red Hat Developer Hub", "create dynamic backend plugin", "scaffold RHDH backend plugin", "new scaffolder action", "create catalog processor", or mentions creating a new backend plugin, backend module, or server-side functionality for Red Hat Developer Hub or RHDH. This skill is specifically for backend plugins - for frontend plugins, use the separate frontend plugin skill.
44
---
55

66
## Purpose
77

8-
Bootstrap a new **backend** dynamic plugin for Red Hat Developer Hub (RHDH). RHDH is the enterprise-ready Backstage applicationthat supports dynamic plugins - plugins that can be installed or uninstalled without rebuilding the application.
8+
Bootstrap a new **backend** dynamic plugin for Red Hat Developer Hub (RHDH). RHDH is the enterprise-ready Backstage application that supports dynamic plugins - plugins that can be installed or uninstalled without rebuilding the application.
99

1010
> **Note:** This skill covers **backend plugins only**. Frontend dynamic plugins have different requirements (Scalprum configuration, mount points, dynamic routes) and are covered in a separate skill.
1111
@@ -49,36 +49,40 @@ Check the target RHDH version and find the compatible Backstage version. Consult
4949

5050
Ask the user which RHDH version they are targeting if not specified.
5151

52-
## Step 2: Create Backstage Application
52+
## Steps 2-3: Create Backstage Application & Backend Plugin
5353

54-
Create a new Backstage application in the current directory using the version-appropriate create-app:
54+
Use the scaffold script to automate app creation, dependency installation, and plugin generation in one command:
5555

5656
```bash
57-
# For RHDH 1.8 (adjust version as needed)
58-
echo "backstage" | npx @backstage/create-app@0.7.3 --path .
57+
python skills/create-backend-plugin/scripts/scaffold.py \
58+
--rhdh-version 1.9 \
59+
--plugin-id my-plugin \
60+
--path ./my-app
5961
```
6062

61-
After creation, install dependencies:
62-
63-
```bash
64-
yarn install
65-
```
63+
The script:
64+
- Looks up the correct `@backstage/create-app` version for the target RHDH release
65+
- Creates the Backstage app (idempotent — skips if `package.json` already exists)
66+
- Runs `yarn install`
67+
- Generates the backend plugin via `yarn new --select backend-plugin --option id=<plugin-id>`
6668

67-
The only purpose this serves is to ensure you can later create the plugin using the correct version of the Backstage CLI. All development and testing will be done in the plugin directory.
69+
Use `--json` for structured output, or `--create-app-version` to override the auto-detected version. Run with `--help` for all options.
6870

69-
## Step 3: Create Backend Plugin
71+
### Manual alternative
7072

71-
Generate a new backend plugin using the Backstage CLI:
73+
If you prefer to run the commands manually:
7274

7375
```bash
74-
yarn new
75-
```
76+
# Step 2: Create Backstage app
77+
# Consult ../rhdh/references/versions.md for the correct create-app version
78+
echo "backstage" | npx @backstage/create-app@0.7.3 --path .
79+
yarn install
7680

77-
When prompted:
81+
# Step 3: Create backend plugin
82+
yarn new --select backend-plugin --option id=my-plugin
83+
```
7884

79-
1. Select **"backend-plugin"** as the plugin type
80-
2. Enter a plugin ID (e.g., `my-plugin`)
81-
3. The plugin will be created at `plugins/<plugin-id>-backend/`
85+
The only purpose of the Backstage app is to ensure you can create the plugin using the correct version of the Backstage CLI. All development and testing will be done in the plugin directory.
8286

8387
The generated plugin structure:
8488

@@ -191,6 +195,8 @@ For local development/testing, copy `dist-dynamic` to RHDH's `dynamic-plugins-ro
191195
cp -r dist-dynamic /path/to/rhdh/dynamic-plugins-root/<plugin-id>-backend-dynamic
192196
```
193197

198+
> **Windows note:** Use `xcopy /E /I dist-dynamic \path\to\rhdh\dynamic-plugins-root\<plugin-id>-backend-dynamic` or `robocopy dist-dynamic \path\to\rhdh\dynamic-plugins-root\<plugin-id>-backend-dynamic /E` instead of `cp -r`.
199+
194200
See `examples/dynamic-plugins.yaml` for a complete configuration example.
195201

196202
## Common Issues

0 commit comments

Comments
 (0)