feat(rhdh-templates): add a new rhdh-templates skill for authoring and validating Software Templates in RHDH

.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.5.0"
+    "version": "0.5.1"
   },
   "plugins": [
     {
       "name": "rhdh",
       "source": "./",
       "description": "Skills for RHDH plugin lifecycle management",
-      "version": "0.5.0",
+      "version": "0.5.1",
       "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.5.0",
+  "version": "0.5.1",
   "author": {
     "name": "RHDH Store Manager"
   },

README.md

@@ -22,6 +22,29 @@ Build dynamic plugins from scratch — backend or frontend — and get them depl
   - **[export](./skills/create-plugin/references/export.md)** — Export, package (OCI/tgz/npm), and push to a container registry.
   - **[wiring](./skills/create-plugin/references/wiring.md)** — Analyze plugin source and generate `dynamic-plugins.yaml` wiring config.
 
+### Software Templates
+
+Author RHDH Scaffolder templates with guided workflows — templatize existing codebases, create from scratch, and fix common gotchas.
+
+- **[rhdh-templates](./skills/rhdh-templates/SKILL.md)** — Interactive authoring and validation for Software Templates. Includes curated reference catalog (official library + AI quickstarts), worked examples (`nodejs-backend`, `java-springboot`) and bundled JSON Schema validation. Sub-commands:
+  - **[init](./skills/rhdh-templates/references/init.md)** — Check tooling, scaffold template repo layout, optional RHDH connectivity.
+  - **[templatize](./skills/rhdh-templates/references/templatize.md)** — Convert existing codebase into a parameterized template.
+  - **[create](./skills/rhdh-templates/references/create.md)** — Guided from-scratch template authoring when no reference code exists.
+  - **[add-parameter](./skills/rhdh-templates/references/add-parameter.md)** — Add a parameter or parameter group to existing `template.yaml`.
+  - **[add-step](./skills/rhdh-templates/references/add-step.md)** — Add a scaffolder step to existing `template.yaml`.
+  - **[add-skeleton](./skills/rhdh-templates/references/add-skeleton.md)** — Add or parameterize skeleton files with Nunjucks.
+  - **[create-location](./skills/rhdh-templates/references/create-location.md)** — Generate or update root `location.yaml` for catalog registration.
+  - **[fix-gotchas](./skills/rhdh-templates/references/fix-gotchas.md)** — Auto-fix common RHDH template mistakes (raw/endraw blocks, catalog-info path, etc.).
+  - **[validate](./skills/rhdh-templates/references/validate.md)** — Local YAML schema, gotcha validation, and optional Nunjucks lint via `--lint-skeleton` (no RHDH required).
+  - **[list-actions](./skills/rhdh-templates/references/list-actions.md)** — List available Scaffolder actions from a running RHDH instance.
+  - **[dry-run](./skills/rhdh-templates/references/dry-run.md)** — Test template execution via Scaffolder v2 dry-run API.
+  - **[explain-action](./skills/rhdh-templates/references/explain-action.md)** — Show action input schema or template parameter schema.
+  - **[example-catalog](./skills/rhdh-templates/references/example-catalog.md)** — Browse curated reference templates (official library, AI quickstarts, bundled).
+
+```bash
+npx skills add redhat-developer/rhdh-skill --skill rhdh-templates
+```
+
 ### Extensions Catalog
 
 Manage plugins in the [rhdh-plugin-export-overlays](https://github.com/redhat-developer/rhdh-plugin-export-overlays) repository.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "rhdh-skill"
-version = "0.5.0"
+version = "0.5.1"
 description = "Claude Code skill for RHDH plugin development"
 readme = "README.md"
 license = "Apache-2.0"
@@ -15,7 +15,8 @@ include = ["rhdh*"]
 [project.optional-dependencies]
 dev = [
     "pytest>=7.0",
-    "pyyaml>=6.0",  # Only for SKILL.md structure tests
+    "pyyaml>=6.0",  # SKILL.md structure tests and template YAML parsing
+    "jsonschema>=4.0",  # Optional full JSON Schema validation in rhdh-templates
     "ruff>=0.4.0",
 ]
 

skills/rhdh-templates/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: rhdh-templates
+description: >-
+  Author and validate RHDH Software Templates (Scaffolder) with AI-guided workflows. Use when
+  asked to "create software template", "templatize a codebase", "convert repo to
+  template", "write template.yaml", "location.yaml for templates", "scaffolder
+  template", "golden path template", "parameterize skeleton files", "fix template
+  gotchas", "validate template", "dry-run template", "list scaffolder actions",
+  "explain scaffolder action", "Nunjucks in template", "template best practices",
+  "reference templates", "example templates", "what templates do customers use",
+  "Template Editor", or mentions RHDH template
+  authoring, Software Catalog templates, or /rhdh-templates commands. Covers setup,
+  templatize (highest value), from-scratch create, reference example discovery,
+  incremental parameter/step/skeleton authoring, location.yaml generation, common
+  convention fixes, local validation, and live Scaffolder API dry-run/action discovery.
+---
+
+<essential_principles>
+
+## Domain
+
+Software Templates are `kind: Template` entities processed by the Scaffolder. Each template has:
+
+- `template.yaml` — metadata, `spec.parameters` (form), `spec.steps` (actions), `spec.output`
+- `skeleton/` — files copied/templated into the target repo (Nunjucks `{% raw %}` blocks where needed)
+- `location.yaml` (repo root) — `kind: Location` registering all `template.yaml` files for catalog import
+
+Read `references/conventions.md` before editing any template artifact — it encodes RHDH-specific rules that differ from generic Backstage docs.
+
+Read `references/best-practices.md` when authoring or reviewing templates — it encodes Red Hat's 10 tips for repository layout, Template Editor workflow, custom fields, Nunjucks, secrets, type/tags, TechDocs, and maintenance.
+
+## Authoring stance
+
+- **Interactive, not fully automatic.** Templatize proposes parameterization; the user confirms each literal-to-parameter mapping.
+- **Conservative parameterization.** Under-parameterize rather than expose every string — users can add parameters incrementally.
+- **First-try correctness.** Generated artifacts should pass local `validate` with zero critical findings before merge.
+
+## Script paths
+
+All `scripts/` and `references/` paths are relative to this SKILL.md directory. Resolve them before invoking.
+
+</essential_principles>
+
+<setup>
+
+## Setup gates (non-optional before file edits)
+
+| Gate | Required check | If fail |
+|------|----------------|---------|
+| Command | Sub-command reference loaded | Load the matching `references/<command>.md` (or `example-catalog.md` for `examples`) |
+| Layout | Template project initialized or path confirmed | Run `init` or ask user for template repo root |
+| Conventions | `references/conventions.md` read for authoring commands | Read it first |
+
+</setup>
+
+<intake>
+
+## What would you like to do?
+
+| # | Command |
+|---|---------|
+| 1 | `init` |
+| 2 | `templatize` |
+| 3 | `create` |
+| 4 | `add-parameter` |
+| 5 | `add-step` |
+| 6 | `add-skeleton` |
+| 7 | `create-location` |
+| 8 | `fix-gotchas` |
+| 9 | `validate` |
+| 10 | `list-actions` |
+| 11 | `dry-run` |
+| 12 | `explain-action` |
+| 13 | `examples` |
+
+Command descriptions and argument hints: `scripts/command-metadata.json`
+
+**Wait for response before proceeding.**
+
+</intake>
+
+<routing>
+
+| Response | Reference |
+|----------|-----------|
+| 1, "init", "setup", "scaffold", "prerequisites" | [references/init.md](references/init.md) |
+| 2, "templatize", "convert", "parameterize repo", "existing codebase" | [references/templatize.md](references/templatize.md) |
+| 3, "create", "from scratch", "new template" | [references/create.md](references/create.md) |
+| 4, "add-parameter", "add parameter", "form field" | [references/add-parameter.md](references/add-parameter.md) |
+| 5, "add-step", "add step", "scaffolder action", "pipeline step" | [references/add-step.md](references/add-step.md) |
+| 6, "add-skeleton", "skeleton file", "nunjucks" | [references/add-skeleton.md](references/add-skeleton.md) |
+| 7, "create-location", "location.yaml", "register templates" | [references/create-location.md](references/create-location.md) |
+| 8, "fix-gotchas", "fix template", "gotchas", "raw endraw" | [references/fix-gotchas.md](references/fix-gotchas.md) |
+| 9, "validate", "lint template", "check template", "lint-nunjucks", "lint nunjucks", "djlint", "nunjucks lint" | [references/validate.md](references/validate.md) |
+| 10, "list-actions", "list actions", "scaffolder actions" | [references/list-actions.md](references/list-actions.md) |
+| 11, "dry-run", "dry run", "test template remotely" | [references/dry-run.md](references/dry-run.md) |
+| 12, "explain-action", "action schema", "parameter schema" | [references/explain-action.md](references/explain-action.md) |
+| 13, "examples", "reference templates", "show me templates", "what templates exist" | [references/example-catalog.md](references/example-catalog.md) |
+| First word doesn't match | Infer from context. "Turn my Spring Boot app into a template" → `templatize`. "Add owner picker to my template" → `add-parameter`. "Does my template validate?" → `validate`. "What templates do customers use?" → `examples`. |
+
+</routing>
+
+<cli_commands>
+
+## Bundled scripts
+
+```bash
+# Resolve skill directory (adjust if SKILL.md path differs)
+SKILL_DIR="<path-to>/skills/rhdh-templates"
+
+python "$SKILL_DIR/scripts/init.py" --help
+python "$SKILL_DIR/scripts/analyze.py" --help
+python "$SKILL_DIR/scripts/create_location.py" --help
+python "$SKILL_DIR/scripts/fix_gotchas.py" --help
+python "$SKILL_DIR/scripts/validate.py" --help
+python "$SKILL_DIR/scripts/list_actions.py" --help
+python "$SKILL_DIR/scripts/dry_run.py" --help
+python "$SKILL_DIR/scripts/explain_action.py" --help
+python "$SKILL_DIR/scripts/list_examples.py" --help
+```
+
+Run `init.py` for deterministic tooling checks and project scaffolding. Use `analyze.py` during `templatize` Phase 1. Use `list_examples.py` during `create`, `templatize`, or `examples` to rank upstream reference templates. Use `create_location.py` and `fix_gotchas.py` where the reference files direct you — they produce structured JSON when piped.
+
+Validation scripts: `validate.py` for local checks (include `--lint-skeleton` for Nunjucks/djLint); `list_actions.py`, `dry_run.py`, and `explain_action.py` require a reachable RHDH `--rhdh-url` and optional bearer token (`RHDH_TOKEN` env or `--token`).
+
+</cli_commands>
+
+<reference_index>
+
+| File | Load when... |
+|------|-------------|
+| `references/conventions.md` | Any authoring command — RHDH template rules |
+| `references/best-practices.md` | Authoring/review — Red Hat 10 tips and pre-merge checklist |
+| `references/template-structure.md` | Writing or reviewing `template.yaml` anatomy |
+| `references/parameter-widgets.md` | Choosing form fields and UI widgets for parameters |
+| `references/example-catalog.md` | Command `examples` or picking upstream study references (`assets/example-catalog.json` is the data source; bundled templates under `assets/examples/`) |
+| `references/schemas/template-v1beta3.schema.json` | Bundled JSON Schema for deep `validate` checks |
+
+</reference_index>