generate-agv-description

name	generate-agv-description
description	Generate AgnosticV catalog description from lab or demo content for RHDP provisioning.

---

context: main model: sonnet

generate-agv-description

Generate a properly formatted description.adoc file for AgnosticV catalog entries that appears in the Red Hat Demo Platform UI.

Quick Start

How to use:

1. Run: /generate-agv-description (from any directory)
2. Choose: "Yes - I have a Showroom" or "No - Manual entry"
3. If YES: Provide path to your Showroom (or press Enter to use current directory)
4. Review auto-extracted information and adjust as needed
5. Preview and confirm
6. Done! Optionally commit to git

Example workflow:

# Can run from anywhere
cd ~/work/code/agnosticv/catalogs/my-catalog

# Start skill
/generate-agv-description

# Choose option 1 (Yes - I have Showroom)
# Provide path: /Users/psrivast/work/code/showroom-ai-lab
# Or press Enter if already in showroom directory

# Skill auto-extracts content and suggests everything

What This Skill Does

Interactively gathers information about your lab/demo and generates a complete description.adoc file following RHDP catalog standards.

Smart features:

• Reads your Showroom guide to auto-extract modules, technologies, and structure
• Pulls author info from git config
• Detects AgnosticV catalog paths automatically
• Suggests content based on guide analysis
• Validates output before writing
• Offers to commit changes and update catalog files

Information Gathered

This skill will ask you for:

0. Do you have a Showroom? (FIRST - always asked)

   • Choose: "Yes - I have Showroom" or "No - Manual entry"
   • If YES: Provide path (or press Enter for current directory)
   • Auto-extracts module structure, technologies, and agenda
   • If NO: All questions require manual answers

1. Brief Overview

   • What is this thing showing? (2-3 sentences)
   • MUST start with main product/technology name (NOT "This workshop/demo/lab")
   • What is the intended use?
   • Smart feature: If guide provided, suggests overview from content starting with product name

2. Warnings (optional)

   • Any important notices (e.g., GPU availability, resource requirements)
   • These appear after the overview on the UI tile
   • Smart feature: Checks guide for prerequisites automatically

3. Guide Link (GitHub Pages URL)

   • Link to rendered Showroom guide (GitHub Pages)
   • Typically: https://rhpds.github.io/showroom-{repo-name}
   • Or repository/document URL if not using GitHub Pages
   • Smart feature: Auto-detects from git remote and converts to GitHub Pages URL

4. Featured Technology and Products

   • Key products/technologies (not everything, just what matters)
   • Version numbers
   • Examples: OpenShift 4.17, Ansible Automation Platform 2.5, etc.
   • Smart feature: Suggests technologies found in guide content

5. Detailed Overview/Agenda (optional)

   • Detailed breakdown of what learners will do
   • Module-by-module or step-by-step agenda
   • Smart feature: Auto-generates from module titles if guide provided

6. Authors and Contact

   • Lab/Demo author name(s) - defaults from git config
   • Slack channel for questions - defaults to #forum-rhdp-content
   • Author's Slack handle for tagging

Output

Generates a complete description.adoc file in AsciiDoc format ready to commit to your AgnosticV catalog entry.

Structure

The generated description.adoc follows this structure:

1. Brief overview (2-3 sentences)

   • MUST start with main product/technology name
   • What is this thing showing?
   • What is the intended use?
   • NEVER use "This workshop", "This demo", "This hands-on lab", or "This lab" at the start
   • NEVER use the word "workshop" anywhere

2. Warnings (optional)

   • These come after the brief overview so they don't waste space on the UI tile
   • For example, a message about GPU availability would go here

3. Link to rendered version of guide (GitHub Pages)

   • This should almost always be a link to the rendered Showroom on GitHub Pages
   • Format: https://rhpds.github.io/showroom-{repo-name}
   • If no Showroom, a link to the repo or document being used

4. Featured Technology and Products

   • Do not list every product, list the ones that matter
   • Include versions and maintain this list
   • Use common sense for how much to include

5. Detailed overview/agenda (optional)

   • You can write this yourself, or
   • Auto-generated by analyzing your Showroom content

6. Lab/Demo authors and contact information

   • This isn't for support with RHDP, this is for questions or issues about the content
   • Format: "Go to Slack and tag {author} in this channel"

---

Execution

When this skill runs, gather the following information interactively:

Step 0: Locate Showroom Content (FIRST)

CRITICAL: ALWAYS ask for Showroom path first, regardless of current directory.

1. Always ask this question first:

   Is this catalog based on a Showroom guide?
   
   If you have a Showroom repository, I can auto-extract:
   - Module structure and titles
   - Technologies and products
   - Learning objectives
   - And suggest content for you
   
   Options:
   1. Yes - I have a Showroom (I'll ask for path)
   2. No - Skip Showroom (manual entry)
   
   Your choice: [1/2]
   

2. If user chooses 1 (YES - has Showroom):

   What is the local path to your Showroom repository?
   
   Current directory: {{ current_directory }}
   
   Options:
   - Press Enter to use current directory ({{ current_directory }})
   - Type full path (e.g., /Users/psrivast/work/code/showroom-ai-lab)
   
   Your Showroom path: [Enter or type path]
   

3. If user chooses 2 (NO - skip Showroom):

   • Skip to manual entry (Step 1)
   • All questions will require manual answers

After getting Showroom path:

1. Validate the path:

   • Check if directory exists
   • Check if it contains site.yml or antora.yml
   • Check if it has content/modules/ structure
   • If NOT valid: "Directory doesn't appear to be a Showroom repo. Try again? [Yes/No]"

2. Read the guide structure:

   • Look for content/modules/*.adoc files or content/modules/ROOT/pages/*.adoc
   • Read antora.yml or site.yml for title and metadata
   • Extract module titles from each module file

3. Extract key information:

   • Lab/demo title
   • Module titles (for agenda)
   • Technologies mentioned in the guide
   • Any warnings or prerequisites mentioned
   • Try to detect content type: Check for Know/Show sections (likely demo) vs Exercise sections (likely lab)
   • Note: Detection is not always reliable - always confirm with user in Step 1

4. Use extracted info to pre-populate suggestions:

   • Show the user what you found
   • Offer to use this as a starting point
   • Allow user to edit/override

Step 1: Content Type and Basic Information

First, determine content type (ALWAYS ask, even if detected from Showroom):

What type of content is this?

1. Lab (hands-on exercises, learner-driven)
2. Demo (presenter-led demonstration)

Your choice: [1/2]

If Showroom was read and content type detected:

• Show detected type: "I detected this is a [lab/demo] based on the content structure."
• Ask for confirmation: "Is this correct? [1: Lab, 2: Demo]"

Store the content type for use in overview generation and output location.

Ask the user:

• What is this lab/demo about? (2-3 sentence overview)

  CRITICAL FORMATTING RULES:

  • ❌ NEVER start with "This demo", "This hands-on lab", "This workshop", or "This lab"
  • ✅ ALWAYS start with the main product/technology name
  • ❌ NEVER use the word "workshop" anywhere in the overview
  • ✅ Use "lab", "demo", "guide", or "content" instead

  Examples:

  ❌ WRONG:

  This workshop teaches you to build AI/ML workloads using Red Hat OpenShift AI.
  This hands-on lab demonstrates building a RAG chatbot.
  This demo shows how to deploy applications on OpenShift.
  

  ✅ CORRECT:

  Red Hat OpenShift AI enables data scientists to build and deploy machine learning
  workloads at scale. Learners explore model serving, pipelines, and integration with
  enterprise data sources.
  
  Red Hat OpenShift AI with LiteMaaS provides enterprise-grade model serving for
  RAG-based chatbots. This content demonstrates vector database integration, semantic
  search, and LLM grounding with custom data.
  
  OpenShift Container Platform simplifies application deployment with GitOps workflows.
  This guide covers Argo CD setup, Kustomize overlays, and automated rollouts.
  

  If guide was read:

  • Extract main product/technology from title and content
  • Generate overview starting with product name
  • Show to user for approval/editing
  • Remind user: "Overview starts with product name (not 'This workshop/demo/lab')"

  If manual entry:

  • User can accept, edit, or provide their own
  • Validate that overview starts with product name
  • If starts with "This workshop/demo/lab", ask user to rewrite

• What is the intended use? (self-paced learning, instructor-led, demo, sales enablement, etc.)

  • Use "instructor-led" instead of "workshop"
  • Use "self-paced learning" instead of "self-paced workshop"

• Are there any warnings or special requirements? (optional - GPU needs, resource limits, beta features, etc.)

  • If guide was read, check for any prerequisites mentioned

Step 2: Guide and Technology

Ask the user:

• What is the link to the rendered Showroom guide (GitHub Pages URL)?

  What is the GitHub Pages URL for your rendered Showroom guide?
  
  This is typically published at:
  https://rhpds.github.io/showroom-{repo-name}
  
  Where {repo-name} is your repository name without the .git extension.
  
  Examples:
  - https://rhpds.github.io/showroom-ai-ml-lab
  - https://rhpds.github.io/showroom-ansible-automation
  
  If not using GitHub Pages, provide your guide URL (repo or docs link).
  
  Your Showroom GitHub Pages URL:
  

  • If Showroom path was provided in Step 0, try to auto-detect from git remote
  • Run: git -C {showroom_path} remote get-url origin to get repo URL
  • Convert to GitHub Pages format:
    • From: [e-mail]:rhpds/showroom-ai-ml-lab.git
    • Or: https://github.com/rhpds/showroom-ai-ml-lab.git
    • To: https://rhpds.github.io/showroom-ai-ml-lab
  • Show detected URL and ask for confirmation: "Is this correct? [Yes/Edit]"

• What are the featured technologies and products? (with versions)

  • If guide was read, suggest technologies found in the content
  • Prompt: "List the key products with versions, e.g., 'OpenShift 4.17, AAP 2.5, PostgreSQL 16'"

Step 3: Detailed Content (Optional)

Ask the user:

• Would you like to include a detailed overview/agenda?
  • If guide was read, automatically generate agenda from module titles
  • Show the generated agenda and ask if they want to use/edit it
  • If no guide: "Provide the module-by-module or detailed agenda content"
  • If user declines: Skip this section

Step 4: Authors and Contact

Smart defaults: Extract from git config before asking:

1. Run git config user.name to get author name
2. Suggest this as default: "Author: [Name from git] (press Enter to accept or type to override)"
3. Ask for Slack channel (default: #forum-rhdp-content)
4. Ask for Slack handle (try to infer from git email or ask)

Step 5: Determine Output Location

Smart detection:

1. Check if currently in an AgnosticV catalog directory structure
   • Look for pattern: */agnosticv/*/catalog_items/*/description.adoc
2. If in AgnosticV structure, suggest: ./description.adoc
3. If in Showroom repo, suggest: ./description.adoc or ask for AgV catalog path
4. Otherwise ask: "Where should I save description.adoc?"
5. Check if file exists and ask to overwrite if needed

Step 6: Generate description.adoc

Using the gathered information, generate a description.adoc file with this structure:

[Brief overview - 2-3 sentences about what this shows and intended use]

[WARNING]
====
[Warning text if provided]
====

link:[Guide URL][Access the rendered lab guide^]

== Featured Technology and Products

* [Product 1] [Version]
* [Product 2] [Version]
* [Product 3] [Version]

== What You Will Learn

[Detailed agenda/overview content if provided]

== Authors and Contact

*Authors:* [Author names]

For questions or issues with this content, please reach out in the [Slack channel] Slack channel and tag [author handle].

NOTE: This is for content questions only. For RHDP platform support, use #forum-rhdp.

Formatting Rules:

• Brief overview: NO heading, just 2-3 sentences at the top
• Warnings: Use AsciiDoc [WARNING] block with ==== delimiters
• Guide link: Use link:url[Link Text^] format (^ opens in new tab)
• Technology list: Level 2 heading (==) with bullet points
• Detailed overview: Level 2 heading (==) with content
• Authors: Level 2 heading (==) with formatted contact info

Step 7: Preview and Confirm

Before writing the file:

1. Show a preview of the generated description.adoc
2. Ask: "Does this look good? (yes/edit/cancel)"
   • yes: Write the file and complete
   • edit: Ask what to change and regenerate
   • cancel: Exit without writing

Step 8: Write and Verify

1. Write the file to the determined location
2. Confirm: "✓ Created description.adoc at [path]"
3. Validate the AsciiDoc syntax (check for common issues)
4. Offer next steps:
   • "Would you like me to commit this to git?"
   • "Should I also update the AgnosticV common.yaml file?"

Step 9: Optional Follow-up Actions

If user requests:

• Git commit: Create commit with message "Add/update catalog description for [lab name]"
• Update common.yaml: Add or update catalog entry if in AgnosticV repo
• Generate README: Create a README.md version for GitHub display

---

Example Output

Red Hat OpenShift AI with LiteMaaS provides enterprise-grade model serving for RAG-based chatbots. Learners deploy a complete AI application stack with vector databases for semantic search and explore the RAG pattern for grounding LLMs with custom data.

Intended for self-paced learning and instructor-led sessions.

[WARNING]
====
This lab requires GPU availability. Ensure your cluster has GPU nodes provisioned before deploying.
====

link:https://showroom.redhat.com/workshops/rag-chatbot[Access the rendered lab guide^]

== Featured Technology and Products

* Red Hat OpenShift AI 2.17
* OpenShift 4.17
* LiteMaaS (Model as a Service)
* PostgreSQL 16 with pgvector
* Ansible Automation Platform 2.5

== What You Will Learn

* *Module 1:* Deploy vector database with pgvector on OpenShift
* *Module 2:* Configure LiteMaaS virtual keys for model access
* *Module 3:* Build RAG pipeline with document ingestion
* *Module 4:* Deploy chatbot frontend and test queries
* *Module 5:* Monitor and optimize RAG performance

== Authors and Contact

*Authors:* Prakhar Srivastava

For questions or issues with this content, please reach out in the #forum-rhdp-content Slack channel and tag @psrivast.

NOTE: This is for content questions only. For RHDP platform support, use #forum-rhdp.

---

Best Practices

1. Keep the overview concise - The first 2-3 sentences appear on the catalog tile
2. List only key products - Don't overwhelm with every dependency
3. Include version numbers - Helps users know if content is current
4. Make warnings visible - Put important requirements right after overview
5. Always link to Showroom - Rendered guides are better than raw repos
6. Make contact clear - Slack channel + author tag is the preferred pattern

---

Tips for Best Results

For maximum automation:

• Run the skill from your Showroom guide directory
• Ensure your Showroom modules have clear titles
• Have your git config set up (git config user.name)

Common Showroom patterns recognized:

• content/modules/*.adoc - Standard Antora structure
• content/modules/ROOT/pages/*.adoc - Showroom structure
• Module title format: = Module Title (first line of module file)
• Prerequisites in index or first module

If auto-detection isn't working:

• Verify antora.yml or site.yml exists in your Showroom root
• Check that modules are in content/modules/ directory
• Provide the full absolute path when asked

After generation:

• Review the preview carefully before writing
• The description appears on RHDP catalog tiles, so clarity matters
• Test the Showroom link to ensure it's correct

Integration with Other Skills

Typical workflow:

1. /create-lab or /create-demo - Create Showroom content first
2. /verify-content - Verify quality
3. /generate-agv-description - Generate catalog description ← YOU ARE HERE
4. Manual: Copy to AgV catalog directory (if not already there)
5. Manual: Test catalog in RHDP Integration
6. Manual: Create PR to AgnosticV repository