Merge pull request #27 from redhat-developer/fix/skill-audit-fixes

fix: skill audit fixes — broken refs, descriptions, fallbacks

Author: schultzp2020

skills/create-plugin/SKILL.md

@@ -8,40 +8,60 @@ description: >
   "configure mount points", "create dynamic route", "add entity card", "scaffold
   RHDH plugin", "publish plugin to registry", "create tgz archive", or mentions
   creating, exporting, packaging, or wiring a Backstage plugin for Red Hat Developer
-  Hub. Covers backend plugins (APIs, scaffolder actions, processors), frontend plugins
+  Hub. Also use when asked to "build a plugin from scratch", "dynamic plugin
+  tutorial", "RHDH plugin from scratch", or "build Backstage plugin for RHDH".
+  Covers backend plugins (APIs, scaffolder actions, processors), frontend plugins
   (pages, cards, themes), export/packaging (OCI, tgz, npm), and frontend wiring
   configuration (mount points, routes, entity tabs, themes).
 compatibility: "Node.js 22+, Yarn, podman or docker. Windows, macOS, Linux."
 ---
 
+<essential_principles>
+
 ## Prerequisites
 
 - Node.js 22+ and Yarn
 - Container runtime (`podman` or `docker`) for OCI packaging
 - Access to a container registry (e.g., quay.io) for publishing
 
-## Commands
+</essential_principles>
+
+<intake>
+
+## What would you like to do?
+
+| # | Category | Command | Description |
+|---|----------|---------|-------------|
+| 1 | Create | `backend` | Scaffold and implement a backend dynamic plugin |
+| 2 | Create | `frontend` | Scaffold and implement a frontend dynamic plugin |
+| 3 | Package | `export` | Export, package, and push a plugin for RHDH deployment |
+| 4 | Configure | `wiring` | Analyze a frontend plugin and generate wiring config |
+
+Single source of truth for command descriptions: `scripts/command-metadata.json`
 
-| Command | Category | Description | Reference |
-|---------|----------|-------------|-----------|
-| `backend` | Create | Scaffold and implement a backend dynamic plugin | [references/backend.md](references/backend.md) |
-| `frontend` | Create | Scaffold and implement a frontend dynamic plugin | [references/frontend.md](references/frontend.md) |
-| `export` | Package | Export, package, and push a plugin for RHDH deployment | [references/export.md](references/export.md) |
-| `wiring` | Configure | Analyze a frontend plugin and generate wiring config | [references/wiring.md](references/wiring.md) |
+**Wait for response before proceeding.**
 
-### Routing rules
+</intake>
 
-1. **No argument**: Show the command table. Ask what the user wants to do.
-2. **First word matches a command**: Load its reference file and follow it.
-3. **First word doesn't match**: Infer intent from context. "Create a new API plugin" → `backend`. "Package my plugin as OCI" → `export`. "Generate mount points" → `wiring`.
+<routing>
+
+| Response | Reference |
+|----------|----------|
+| 1, "backend", "create backend", "API plugin", "scaffolder action" | [references/backend.md](references/backend.md) |
+| 2, "frontend", "create frontend", "page", "card", "theme" | [references/frontend.md](references/frontend.md) |
+| 3, "export", "package", "OCI", "tgz", "publish", "push" | [references/export.md](references/export.md) |
+| 4, "wiring", "mount points", "routes", "entity tabs" | [references/wiring.md](references/wiring.md) |
+| First word doesn't match | Infer intent from context. "Create a new API plugin" → `backend`. "Package my plugin as OCI" → `export`. "Generate mount points" → `wiring`. |
+
+</routing>
 
 ## Shared Knowledge
 
 > **Script paths:** All `scripts/` and `references/` paths below are relative to this SKILL.md file's directory. Resolve them against the skill directory before invoking.
 
 ### RHDH Version Resolution
 
-Before scaffolding, determine the target RHDH version. Consult `../rhdh/references/versions.md` for the compatibility matrix. Ask the user if not specified.
+Before scaffolding, determine the target RHDH version. Consult `../rhdh/references/versions.md` for the compatibility matrix. If that file is not found (skill installed standalone), ask the user for the target RHDH version directly.
 
 ### Scaffold Script
 
@@ -79,6 +99,8 @@ The typical workflow chains these commands:
 
 Each reference file is self-contained. Load only the one you need.
 
+<reference_index>
+
 ## Reference Index
 
 ### Command References
@@ -107,6 +129,8 @@ Each reference file is self-contained. Load only the one you need.
 | `examples/dynamic-plugins.yaml` | Backend, frontend, multi-plugin, tgz, npm, and local config patterns |
 | `examples/frontend-wiring.yaml` | All frontend wiring patterns — tabs, cards, search, themes, scaffolder |
 
+</reference_index>
+
 ## Common Issues
 
 ### Plugin Not Loading

skills/create-plugin/scripts/command-metadata.json

@@ -1,18 +1,18 @@
 {
   "backend": {
-    "description": "Scaffold and implement a backend dynamic plugin for RHDH. Use when creating a new backend API plugin, backend module, scaffolder action, catalog processor, or authentication module for Red Hat Developer Hub.",
-    "argumentHint": "[plugin description or name]"
+    "description": "Scaffold and implement a backend dynamic plugin (API, scaffolder action, processor).",
+    "argumentHint": "[plugin description or plugin ID]"
   },
   "frontend": {
-    "description": "Scaffold and implement a frontend dynamic plugin for RHDH. Use when creating a new page, entity card, sidebar item, theme, scaffolder field extension, or TechDocs addon for Red Hat Developer Hub.",
-    "argumentHint": "[plugin description or name]"
+    "description": "Scaffold and implement a frontend dynamic plugin (page, card, theme).",
+    "argumentHint": "[plugin description or plugin ID]"
   },
   "export": {
-    "description": "Export and package a Backstage plugin as an RHDH dynamic plugin. Use when exporting as OCI image, tgz archive, or npm package, pushing to a container registry, or bundling multiple plugins.",
-    "argumentHint": "[plugin directory or packaging options]"
+    "description": "Export, package, and push a plugin for RHDH deployment (OCI, tgz, npm).",
+    "argumentHint": "[plugin directory or plugin ID]"
   },
   "wiring": {
-    "description": "Analyze an existing Backstage frontend plugin and generate the RHDH dynamic plugin wiring configuration. Use when generating dynamic-plugins.yaml config, mount points, routes, entity tabs, or theme config.",
-    "argumentHint": "[plugin directory to analyze]"
+    "description": "Analyze a frontend plugin and generate dynamic-plugins.yaml wiring config.",
+    "argumentHint": "[plugin directory or plugin ID]"
   }
 }

skills/overlay/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: overlay
-description: Manages the rhdh-plugin-export-overlays repository — onboards plugins to the Extensions Catalog, updates plugin versions, fixes overlay build failures, triages and analyzes PRs, triggers publishes, and manages plugin workspaces. Use when working with overlays, importing plugins, debugging CI, checking PRs, or bumping versions.
+description: >-
+  Manages the rhdh-plugin-export-overlays repository — onboards plugins to the
+  Extensions Catalog, updates plugin versions, fixes overlay build failures,
+  triages and analyzes PRs, triggers publishes, and manages plugin workspaces.
+  Use when working with overlays, importing plugins, debugging CI, checking PRs,
+  bumping versions, or mentions "Extensions Catalog", "overlay build failed",
+  "plugin registry", "overlay PR", "overlay doctor", "plugin import",
+  "add plugin to catalog", "onboard plugin", or "plugin workspace".
 ---
 
 <cli_setup>
@@ -136,7 +143,7 @@ gh pr view <number> --repo $REPO --json statusCheckRollup \
 2. No `do-not-merge` label
 3. Publish check not already successful
 
-See `../rhdh/references/github-reference.md` for full patterns.
+See `../rhdh/references/github-reference.md` for full patterns. If unavailable, use standard `gh` CLI patterns.
 </inline_publish_trigger>
 
 <reference_index>
@@ -146,7 +153,7 @@ See `../rhdh/references/github-reference.md` for full patterns.
 **PR label priorities:** references/label-priority.md
 **RHDH Local testing:** references/rhdh-local.md
 
-**For GitHub/JIRA patterns:** See `../rhdh/references/`
+**For GitHub/JIRA patterns:** See `../rhdh/references/` (if unavailable, use standard `gh` / `acli` patterns)
 </reference_index>
 
 <workflows_index>

skills/rhdh-jira/SKILL.md

@@ -5,10 +5,16 @@ description: |
 compatibility: "acli (Atlassian CLI) on PATH. Python 3 for scripts. Windows, macOS, Linux."
 ---
 
+<essential_principles>
+
 # RHDH Jira
 
 Foundational skill for interacting with RHDH's Jira instance via the Atlassian CLI (`acli`). Covers all four active projects, issue types, workflows, custom fields, and JQL patterns.
 
+</essential_principles>
+
+<intake>
+
 ## Commands
 
 | Command | Description | Reference |
@@ -25,12 +31,20 @@ Foundational skill for interacting with RHDH's Jira instance via the Atlassian C
 
 Single source of truth for command descriptions: `scripts/command-metadata.json`
 
+**Wait for response before proceeding.**
+
+</intake>
+
+<routing>
+
 ### Routing rules
 
 1. **No argument**: Show the command menu. Ask what to do.
 2. **First word matches a command**: Load its reference file and follow it.
 3. **First word doesn't match**: General Jira invocation using the full argument as context — use the reference files table below to decide what to load.
 
+</routing>
+
 ## Prerequisites
 
 Run `scripts/setup.py` to verify everything is configured:
@@ -95,6 +109,8 @@ RHDHPAI (Plugins and AI) is **archived** — JQL queries against it will fail.
 - **Sub-task** — child of any issue type above
 - **Vulnerability** — CVE tracking in RHIDP (Product Security)
 
+<reference_index>
+
 ## Reference Files
 
 Load only what the current task requires.
@@ -123,6 +139,8 @@ Load only what the current task requires.
 | `references/grill.md` | Shared challenging behavior for issue creation grills: sizing, completeness, scope, risks, cross-referencing. |
 | `references/sizing.md` | T-shirt sizing guide for Features/Epics and Fibonacci story points for Stories/Tasks. Used during grills and refinement. |
 
+</reference_index>
+
 ## Common Gotchas
 
 1. **`acli auth status` lies.** It checks OAuth, not API token auth. Always returns "unauthorized" with token auth even when Jira works fine. Use `acli jira project list --recent 1` as a smoke test instead.

skills/rhdh-local/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: rhdh-local
-description: Skill for testing RHDH plugins locally using the rhdh-local-setup customization system. Covers enabling/disabling plugins, switching modes, running end-to-end plugin tests, starting/stopping RHDH (up/down), health checks, troubleshooting errors (504, startup failures), and backup/restore of configurations.
+description: >-
+  Test RHDH plugins locally using the rhdh-local-setup customization system.
+  Covers enabling/disabling plugins, switching modes, running end-to-end plugin
+  tests, starting/stopping RHDH (up/down), health checks, troubleshooting errors
+  (504, startup failures), and backup/restore of configurations. Use when asked
+  to "test plugin locally", "local RHDH setup", "start local Developer Hub",
+  "rhdh-local-setup", "local development environment", "podman compose RHDH",
+  or "run RHDH on my machine".
 ---
 
 <essential_principles>
@@ -58,7 +65,7 @@ What would you like to do with your local RHDH instance?
 **Environment variables (.env reference):** `references/env-reference.md`
 **Troubleshooting & comparative testing:** `references/troubleshooting.md`
 **Container lifecycle, startup scripts, network namespace:** `references/troubleshooting.md` — restart patterns, 504 debugging, network namespace rules
-**Dynamic plugin YAML format, OCI references:** `../overlay/references/rhdh-local.md` section `<dynamic_plugins_config>`
+**Dynamic plugin YAML format, OCI references:** `../overlay/references/rhdh-local.md` section `<dynamic_plugins_config>` (if unavailable, see `rhdh-plugin-export-overlays` repo README for YAML format)
 </reference_index>
 
 <skills_index>

skills/rhdh-pr-review/SKILL.md

@@ -9,6 +9,7 @@ This skill uses the orchestrator CLI for activity tracking. **Set up first:**
 ```bash
 RHDH=../rhdh/scripts/rhdh
 ```
+
 </cli_setup>
 
 <essential_principles>
@@ -66,9 +67,8 @@ Both paths preserve existing Backstage CRs, config, and Keycloak state — only
 | Reference | Purpose | Path |
 |-----------|---------|------|
 | operator-pr-images | CI image extraction and validation | `references/operator-pr-images.md` |
-| github-reference | gh CLI patterns, PR queries | `../rhdh/references/github-reference.md` |
-| rhdh-repos | RHDH ecosystem repository map | `../rhdh/references/rhdh-repos.md` |
-
+| github-reference | gh CLI patterns, PR queries | `../rhdh/references/github-reference.md` (if unavailable, use standard `gh` CLI patterns) |
+| rhdh-repos | RHDH ecosystem repository map | `../rhdh/references/rhdh-repos.md` (if unavailable, see CONTEXT.md for repo list) |
 
 </reference_index>
 

skills/rhdh-test-plan-review/SKILL.md

@@ -59,7 +59,7 @@ Provide a Jira ticket ID or URL (e.g., `RHIDP-8994`) to begin.
 |-----------|---------|------|
 | sources | Lifecycle URLs and extraction guidance per platform/integration | `references/sources.md` |
 | google-sheets-setup | One-time gcloud auth setup for schedule sheet access | `references/google-sheets-setup.md` |
-| rhdh-jira auth | Jira REST API token setup and curl patterns | `~/.claude/skills/rhdh-jira/references/auth.md` |
+| rhdh-jira auth | Jira REST API token setup and curl patterns | `../rhdh-jira/references/auth.md` |
 
 </reference_index>
 

skills/rhdh-test-plan-review/scripts/gcloud_token.py

@@ -1,4 +1,8 @@
-"""Shared gcloud access token helper for rhdh-test-plan-review scripts."""
+"""Shared gcloud access token helper for rhdh-test-plan-review scripts.
+
+Library module — imported by check_gsheets.py and fetch_schedule.py.
+Not a CLI script; do not invoke directly.
+"""
 
 import shutil
 import subprocess

skills/rhdh/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: rhdh
-description: Handles all RHDH-related work — "RHDH", "Red Hat Developer Hub", or "Developer Hub". Primary entry point for plugin development, overlay management, environment setup, repo navigation, version compatibility, CI/CD, configuration, debugging, and general RHDH ecosystem knowledge. Routes to specialized sub-skills as needed.
+description: >-
+  Handles all RHDH-related work — "RHDH", "Red Hat Developer Hub", or "Developer
+  Hub". Primary entry point for plugin development, overlay management,
+  environment setup, repo navigation, version compatibility, CI/CD,
+  configuration, debugging, and general RHDH ecosystem knowledge. Routes to
+  specialized sub-skills as needed. Use when asked about RHDH version
+  compatibility, RHDH CI pipeline, RHDH configuration, which RHDH repo to use,
+  RHDH release status, RHDH debugging, or any Developer Hub question.
 ---
 
 <cli_setup>
@@ -112,7 +119,7 @@ What would you like to do?
 
 ### Test Plan Tasks
 
-*For rhdh test plan review in jira* 
+*For rhdh test plan review in jira*
 
 9. **Review Test Plan content** — Reviews an RHDH test plan Jira ticket and suggests platform/integration version updates based on support lifecycle pages and RHDH release milestones
 

skills/skill-maker/SKILL.md

@@ -15,6 +15,7 @@ What do you need to do?
 2. **Create a new skill** — Interview, draft, and review from scratch
 3. **Consolidate skills** — Merge multiple skills into fewer
 
+**Wait for response before proceeding.**
 </intake>
 
 <routing>