Add rhdh-templates skill

AGENTS.md

@@ -68,6 +68,7 @@ If told an implementation was wrong, apply the correction and then record what w
 
 User-facing skills live under `skills/`:
 
+- `rhdh-templates` — Software Templates authoring and validation
 - `skill-maker` — Create, audit, and consolidate Agent Skills
 
 When adding a skill, update [README.md](./README.md) and keep `SKILL.md` `name` aligned with the directory name per the Agent Skills spec.

README.md

@@ -9,9 +9,35 @@ Agent Skills for adopting and using [Red Hat Developer Hub](https://developers.r
 
 ## What's included
 
-| Skill | Use when you want to… |
-| ----- | --------------------- |
-| [skill-maker](./skills/skill-maker/SKILL.md) | Create, audit, and consolidate Agent Skills following the open standard |
+| Skill                                              | Use when you want to…                                                   |
+| -------------------------------------------------- | ----------------------------------------------------------------------- |
+| [rhdh-templates](./skills/rhdh-templates/SKILL.md) | Author, validate, and test RHDH Software Templates (Scaffolder)         |
+| [skill-maker](./skills/skill-maker/SKILL.md)       | Create, audit, and consolidate Agent Skills following the open standard |
+
+### Software Templates (`rhdh-templates`)
+
+Interactive authoring for RHDH Scaffolder templates — templatize an existing repo, create from scratch, fix common gotchas, and validate locally or against a running instance.
+
+- **[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).
+
+Example prompts:
+
+- "Help me turn this Node.js repo into an RHDH Software Template"
+- "Validate my `template.yaml` and fix Scaffolder gotchas"
+- "List scaffolder actions available on my RHDH instance"
 
 ### Agent Skills authoring (`skill-maker`)
 
@@ -29,9 +55,10 @@ Example prompts:
 npx skills add redhat-developer/rhdh-users-skill-pack
 ```
 
-Or install only this skill:
+Or install only one skill:
 
 ```bash
+npx skills add redhat-developer/rhdh-users-skill-pack --skill rhdh-templates
 npx skills add redhat-developer/rhdh-users-skill-pack --skill skill-maker
 ```
 
@@ -61,11 +88,12 @@ npx skills add ./rhdh-users-skill-pack
 
 1. **Install** the pack (see above).
 2. **Open your project** in an agent-enabled editor or CLI.
-3. **Describe your goal in plain language** — for example, "help me write a skill for our RHDH golden paths."
+3. **Describe your goal in plain language** — for example, "help me turn this repo into an RHDH Software Template."
 
 You can also name the skill explicitly:
 
 ```
+Use the rhdh-templates skill to validate my template.yaml
 Use the skill-maker skill to audit my SKILL.md
 ```
 

pyproject.toml

@@ -12,6 +12,7 @@ requires-python = ">=3.10"
 dev = [
     "pytest>=9.0.3",
     "pyyaml>=6.0",  # SKILL.md structure tests
+    "jsonschema>=4.0",
     "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 are commonly used",
+  "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 example templates exist?" → `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>