Rhdh Templates

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.
• Confirmation is a hard gate. For templatize, write the candidate mapping to the requested proposal artifact and stop; never edit the source until the user confirms.
• Credentials stay out of templates. For publishing steps, wire inputs to existing parameters or documented secret references; never invent, copy, or persist literal tokens, passwords, or credentials.
• Honor explicit task details. When an authoring request already specifies the action, step id, position, and inputs, make that reviewed change directly; do not ask the user to restate details or add unrelated workflow steps.
• Surgical edits only. When the user names one template file and one change, edit only that file. Do not add parameters, steps, or files the user did not request.

Script paths

All scripts/ and references/ paths are relative to this SKILL.md directory. Resolve them before invoking.

Setup gates (non-optional before file edits)

What would you like to do?

Command descriptions and argument hints: scripts/command-metadata.json

Skip the intake menu when the user already gave a concrete task — for example a proposal-only templatize request with an output path, or an add-step request that names the template file, step id, action, and input. Route directly to the matching reference and execute.

Otherwise Wait for response before proceeding.

Bundled scripts

# 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).