rhpds/showroom:create-demo

---

context: main model: claude-opus-4-6

Demo Module Generator

Guide you through creating a Red Hat Showroom demo module using the Know/Show structure for presenter-led demonstrations.

Workflow Diagram

What You'll Need Before Starting

Have these ready before running this skill:

Required:

• 📁 Target directory path - Where to create modules (default: content/modules/ROOT/pages/)
• 📚 Demo materials - At least one of:
  • Product documentation or feature descriptions
  • URLs to technical guides or demos
  • Text describing what to demonstrate
• 🎯 Demo objective - What should the presenter show?

Helpful to have:

• 🏢 Customer scenario - Business context (e.g., "Financial services company needs...")
• 💼 Value proposition - Why does this matter to customers? What problem does it solve?
• ⏱️ Target duration - How long is the demo? (e.g., 10 min, 20 min)
• 👥 Audience - Who is watching? (Technical managers, developers, executives)
• 📝 Previous modules - If continuing existing demo, which module comes before this one

Access needed:

• ✅ Write permissions to the Showroom repository directory

When to Use

Use this skill to create presenter-led demo content, transform technical documentation into business-focused demos, or add modules to existing demos.

Shared Rules

IMPORTANT: This skill follows shared contracts defined in @showroom/docs/SKILL-COMMON-RULES.md:

• Version pinning or attribute placeholders (REQUIRED)
• Reference enforcement (REQUIRED)
• Attribute file location (REQUIRED)
• Image path conventions (REQUIRED)
• Navigation update expectations (REQUIRED)
• Failure-mode behavior (stop if cannot proceed safely)

See SKILL-COMMON-RULES.md for complete details.

Know/Show Structure

Demos use a different format than workshops:

• Know sections: Business context, customer pain points, value propositions, why this matters
• Show sections: Step-by-step presenter instructions, what to demonstrate, expected outcomes

This separates what presenters need to understand (business value) from what they need to do (technical demonstration).

Arguments (Optional)

This skill supports optional command-line arguments for faster workflows.

Usage Examples:

/create-demo                                   # Interactive mode (asks all questions)
/create-demo <directory>                       # Specify target directory
/create-demo <directory> --new                 # Create new demo in directory
/create-demo <directory> --continue <module>   # Continue from specific module

Parameters:

• <directory> - Target directory for demo files
  • Example: /create-demo content/modules/ROOT/pages/
  • If not provided, defaults to content/modules/ROOT/pages/
• --new - Flag to create new demo (generates index + overview + details + module-01)
• --continue <module-path> - Continue from specified previous demo module
  • Example: /create-demo content/modules/ROOT/pages/ --continue content/modules/ROOT/pages/03-module-01-intro.adoc
  • Reads previous module to detect story continuity

How Arguments Work:

• Arguments skip certain questions (faster workflow)
• You can still use interactive mode by calling /create-demo with no arguments
• Arguments are validated before use

Workflow

CRITICAL RULES

1. Ask Questions SEQUENTIALLY

• Ask ONE question or ONE group of related questions at a time
• WAIT for user's answer before proceeding
• Do NOT ask questions from multiple steps together
• Do NOT skip workflows based on incomplete answers

2. Manage Output Tokens

• NEVER output full demo content - Use Write tool to create files
• Show brief confirmations only - "✅ Created: filename (X lines)"
• Keep total output under 5000 tokens - Summaries, not content
• Files are written, not displayed - User reviews with their editor
• Token limit: Claude Code has 32000 token output limit - stay well below it

Example of WRONG approach:

❌ Asking all at once:
1. Module file name?
2. UserInfo variables?
3. Presentation objective?
4. Number of demos?

Example of CORRECT approach:

✅ Ask sequentially:
Step 2: Complete overall demo story planning
[WAIT for completion]

Step 3.1: Module file name?
[WAIT for answer]

Step 3.2: Reference materials?
[WAIT for answer]

etc.

---

Step 1: Parse Arguments (If Provided)

Check if user invoked skill with arguments.

Pattern 1: /create-demo <directory> --new

Parsing arguments: "<directory> --new"

✓ Target directory: <directory>
✓ Mode: Create new demo
✓ Will generate: index.adoc → 01-overview → 02-details → 03-module-01

Validating directory...
[Check if directory exists, create if needed]

Skipping: Step 1 (mode already known: NEW demo)
Proceeding to: Step 2 (Plan Overall Demo Story)

Pattern 2: /create-demo <directory> --continue <module-path>

Parsing arguments: "<directory> --continue <module-path>"

✓ Target directory: <directory>
✓ Mode: Continue existing demo
✓ Previous module: <module-path>

Validating directory...
[Check if directory exists]

Reading previous module: <module-path>
[Extract story, business context, progression]

Skipping: Step 1 (mode already known: CONTINUE)
Skipping: Step 2 (story detected from previous module)
Proceeding to: Step 3 (Module-Specific Details)

Pattern 3: /create-demo <directory>

Parsing arguments: "<directory>"

✓ Target directory: <directory>

Validating directory...
[Check if directory exists]

Skipping: Target directory question
Proceeding to: Step 1 (still need to ask: new vs continue)

Pattern 4: /create-demo (no arguments)

No arguments provided.

Using interactive mode.
Target directory: Will use default (content/modules/ROOT/pages/)

Proceeding to: Step 1 (Determine Context)

Argument Validation:

• If directory doesn't exist, ask user: "Directory not found. Create it? [Yes/No]"
• If --continue but module path invalid, fall back to asking for story recap
• All arguments are optional - skill always works in interactive mode

---

Step 2: Determine Context (New Demo vs Continuation)

SKIP THIS STEP IF:

• User provided --new flag in arguments (already know: NEW demo)
• User provided --continue <module> in arguments (already know: EXISTING demo)

CRITICAL: DO NOT read any files or make assumptions before asking this question!

First, ask the user:

Let's get started! I'll help you create amazing demo content.

Are you creating a new demo or continuing an existing one?

1. 🆕 Creating a NEW demo (I'll help you plan the whole story)
2. ➡️  Continuing an EXISTING demo (I'll pick up where you left off)
3. 🤔 Something else (tell me what you need)

What's your situation? [1/2/3]

ONLY AFTER user answers, proceed based on their response.

Step 2.5: Ask for Showroom Repository Path (if not provided as argument)

SKIP THIS STEP IF: User provided <directory> as argument

Ask the user:

What is the path to your cloned Showroom repository?

You can provide:
- A local path:  /Users/yourname/work/showroom-content/my-demo-showroom
- A GitHub URL:  https://github.com/rhpds/my-demo-showroom
  (I'll clone it to /tmp/ automatically)

Repo path or URL:

If the user provides a GitHub URL (starts with https://github.com/ or [email protected]:):

• Extract the repo name from the URL (last path segment, strip .git suffix if present)
• Use the Bash tool to run: git clone <url> /tmp/<repo-name>
• Set the repo path to /tmp/<repo-name>
• Inform the user: "Cloned to /tmp/<repo-name> — using that as the working directory."

Use content/modules/ROOT/pages/ within that path as the target for demo files.

If continuing existing demo:

• Provide path to previous module (I'll read and auto-detect the story)

Step 3: Plan Overall Demo Story (if new demo)

Great! Let's plan your demo together. I'll ask you a few questions to understand what you're trying to achieve.

IMPORTANT: Ask these as conversational, open-ended questions. Do NOT provide multiple choice options.

Question 1 - The Big Picture:

What's the main message you want to deliver in this demo?

Think about: What should your audience remember after seeing this?

Example: "Show how OpenShift accelerates application deployment for enterprises"

Your answer:

Question 2 - Know Your Audience:

Who will be watching this demo?

Examples: C-level executives, Sales engineers, Technical managers, Partners

Your audience:

And what matters most to them right now? (their business priorities)

Examples: Cost reduction, faster time-to-market, competitive advantage

Their priorities:

Question 3 - The Transformation Story:

Let's create the before-and-after narrative.

What's the customer challenge you're solving?

What's painful about their current state?

What does the ideal future state look like?

Your story:

Question 4 - Customer Scenario:

What company or industry should we feature in this demo?

Examples: "RetailCo" (retail), "FinanceCorp" (banking), "HealthTech" (healthcare)
Or create your own!

Company/industry:

What specific business challenge is driving urgency for them?

Their urgent challenge:

Question 5 - Show the Impact:

What quantifiable improvements will you highlight?

Examples:
- "6 weeks → 5 minutes deployment time"
- "80% reduction in infrastructure costs"
- "10x faster developer productivity"

Your key metrics:

Question 6 - Timing:

How long should the complete demo take?

Typical options: 15min, 30min, 45min

Your target duration:

Then I'll recommend:

• Suggested module/section breakdown
• Know/Show structure for each section
• Business narrative arc across modules
• Key proof points and "wow moments"
• Competitive differentiators to emphasize

You can:

• Accept the recommended flow
• Adjust sections and messaging
• Change business emphasis

---

Step 3.1: Showroom Setup (Recommended for new demos)

For NEW demos only. Skip if adding a module to an existing demo.

Two files to create or fix:

1. site.yml — correct title and ui-bundle theme URL. If default-site.yml exists → rename to site.yml + update gh-pages.yml.
2. ui-config.yml — split view enabled, correct tabs for OCP or VM

Ask all three questions in order — do NOT skip any:

• Q0 — OCP or VM catalog? (determines workloads)
• Q1 — Which tabs/consoles in the right panel? (configures ui-config.yml)
• Q2 — Which Red Hat theme? (sets the ui-bundle URL in site.yml)

→ Full questions, file templates, AgnosticV workload vars: @showroom/skills/create-demo/references/showroom-scaffold.md

---

Step 4: Gather Module-Specific Details

Now for this specific module:

1. Module file name:

   • Module file name (e.g., "03-demo-intro.adoc", "04-platform-demo.adoc")
   • Files go directly in content/modules/ROOT/pages/
   • Pattern: [number]-[topic-name].adoc

2. Reference materials (optional but recommended):

   • URLs to Red Hat product documentation
   • Marketing materials, solution briefs
   • Local files (Markdown, AsciiDoc, PDF)
   • Pasted content
   • Better references = better business value extraction
   • If not provided: Generate from templates and common value propositions

3. UserInfo variables (optional, for accurate showroom content):

   • I must ask the user:

   Q: Do you have access to a deployed environment on demo.redhat.com or integration.demo.redhat.com?
   
   If YES (RECOMMENDED - easiest and most accurate):
   Please share the UserInfo variables from your deployed service:
   
   1. Login to https://demo.redhat.com (or integration.demo.redhat.com)
   2. Go to "My services" → Your service
   3. Click "Details" tab
   4. Expand "Advanced settings" section
   5. Copy and paste the output here
   
   This provides exact variable NAMES like:
   - openshift_cluster_console_url
   - openshift_cluster_admin_username
   - gitea_console_url
   - [custom workload variables]
   
   CRITICAL: I will use these to know WHICH variables exist, NOT to replace them with actual values!
   Variables will stay as placeholders: {openshift_cluster_console_url}
   Showroom replaces these at runtime with actual deployment values.
   
   If NO:
   Q: Would you like to use placeholder attributes for now?
   
   If YES:
   I'll use placeholders: {openshift_console_url}, {user}, {password}
   You can update these later when you get Advanced settings.
   
   If NO (RHDP internal team only):
   I can extract variables from AgnosticV repository if you have it cloned locally.
   This requires AgV path and catalog name.
   Note: Less reliable than Advanced settings.
   

4. Target audience:

   • Sales engineers, C-level executives, technical managers, developers

5. Business scenario/challenge:

   • Auto-detect from previous module (if exists)
   • Or ask for customer scenario (e.g., "RetailCo needs faster deployments")

6. Technology/product focus:

   • Example: "OpenShift", "Ansible Automation Platform"

7. Number of demo parts:

   • Recommended: 2-4 parts (each with Know/Show sections)

8. Key metrics/business value:

   • Example: "Reduce deployment time from 6 weeks to 5 minutes"

9. Diagrams, screenshots, or demo scripts (optional):

   • Do you have architecture diagrams, demo screenshots, or scripts?
   • If yes: Provide file paths or paste content
   • I'll save them to content/modules/ROOT/assets/images/
   • And reference them properly in Show sections

Step 5: Get UserInfo Variables (if applicable)

If UserInfo variables weren't already provided in Step 3, I'll ask for them now.

RECOMMENDED: Get from Deployed Environment (Primary Method)

I'll ask: "Do you have access to a deployed environment on demo.redhat.com or integration.demo.redhat.com?"

If YES (recommended):

Please share the UserInfo variables from your deployed service:

1. Login to https://integration.demo.redhat.com (or demo.redhat.com)
2. Go to "My services" → Find your service
3. Click on "Details" tab
4. Expand "Advanced settings" section
5. Copy and paste the output here

This shows all available variables like:

• openshift_cluster_console_url → For showing presenter where to log in
• openshift_api_server_url → For API demonstrations
• openshift_cluster_admin_username → For admin access demos
• openshift_cluster_admin_password → For demo credentials
• gitea_console_url → For Git server demos
• gitea_admin_username, gitea_admin_password → For Gitea access
• Custom workload-specific variables → Product-specific endpoints

If NO (fallback): I'll use common placeholder variables:

• {openshift_console_url}
• {openshift_api_url}
• {user}
• {password}
• {bastion_public_hostname}

Alternative: Clone collections from AgV catalog

• Read common.yaml from user-provided AgV path
• Clone collections from any repository (agnosticd, rhpds, etc.)
• Read workload roles to find agnosticd_user_info tasks
• Extract variables from data: sections
• Note: Less reliable than deployed environment output

Result: I'll use these in Show sections for precise presenter instructions with actual URLs and credentials.

Step 6: Handle Diagrams, Screenshots, and Demo Scripts (if provided)

If you provided visual assets or scripts:

See @showroom/docs/SKILL-COMMON-RULES.md for image path conventions and clickable image syntax.

For demo scripts or commands:

• Format in code blocks with syntax highlighting
• Use [source,role="execute"] — the execute button lets the presenter click to run commands directly in the Showroom terminal during the demonstration.
• Add presenter notes about what to emphasize:

  [source,role="execute"]
  ----
  oc new-app https://github.com/example/nodejs-ex
  ----
  
  [NOTE]
  ====
  **Presenter Tip:** Emphasize how this single command eliminates 3-5 days of manual setup.
  ====
  

For before/after comparisons:

• Save both images: before-manual-deployment.png, after-automated-deployment.png
• Use side-by-side or sequential placement
• Highlight business transformation visually

Recommended image naming for demos:

• Business context: customer-challenge-overview.png, transformation-roadmap.png
• UI walkthroughs: step-1-login-console.png, step-2-create-project.png
• Results: deployment-success.png, metrics-dashboard.png
• Comparisons: before-state.png, after-state.png

Step 7: Fetch and Analyze References

Based on your references, I'll:

• Fetch URLs and extract technical capabilities
• Read local files
• Identify business value propositions
• Extract metrics and quantifiable benefits
• Map technical features to business outcomes
• Combine with AgnosticV variables (if provided)
• Integrate provided diagrams and screenshots strategically

Reference Tracking (for conclusion generation):

• Track all references used across all modules
• Store reference URLs, titles, and which modules used them
• References will be consolidated in the conclusion module, NOT in individual modules
• Each module can cite sources inline (e.g., "According to Red Hat's Total Economic Impact study...") but the formal References section will only appear in the conclusion

Step 8: Read Templates and Verification Criteria (BEFORE Generating)

CRITICAL: Read templates BEFORE generating any content.

Template source — check the Showroom repo first:

The user's Showroom repo may contain a templates/ directory with up-to-date patterns. Always prefer these over the marketplace's built-in templates.

# Check if user's Showroom repo has demo templates
ls {showroom_repo_path}/examples/demo/templates/ # if exists use examples/ 2>/dev/null

If examples/demo/templates/ exists in the Showroom repo — read from there:

• {showroom_repo_path}/examples/demo/templates/index.adoc — Facilitator/presenter guide (output as index.adoc)
• {showroom_repo_path}/examples/demo/templates/01-overview.adoc
• {showroom_repo_path}/examples/demo/templates/02-details.adoc
• {showroom_repo_path}/examples/demo/templates/03-module-01.adoc — Uses Know/Show structure
• {showroom_repo_path}/examples/demo/templates/99-conclusion.adoc

If examples/demo/templates/ does NOT exist — use bundled plugin templates:

• @showroom/templates/demo/00-index.adoc — Facilitator/presenter guide
• @showroom/templates/demo/03-module-01.adoc — Know/Show structure
• @showroom/templates/demo/01-overview.adoc — Business context overview
• @showroom/templates/demo/99-conclusion.adoc — Conclusion template

Key rules from the templates:

• Demo index.adoc is a facilitator/presenter guide — NOT learner-facing (opposite of workshop)
• All demo modules follow Know/Show structure: === Know (background, business value, why) then === Show (step-by-step presenter actions)
• Both output files are named index.adoc regardless of template source filename

The user's examples/ directory reflects the latest nookbag patterns and may be more current than the marketplace copies. Always use the repo's own templates when available.

See @showroom/docs/SKILL-COMMON-RULES.md for verification prompt file lists and usage.

Step 9: Generate Demo Module (Using Verification Criteria)

IMPORTANT: Use the bundled demo templates read in Step 8 as quality references.

Apply patterns from the bundled templates to new demo content:

• Know/Show structure and separation
• Business value messaging style
• Presenter guidance and talk track format ("What I say", "What I do")
• Code block formatting and syntax highlighting
• Image references (link=self,window=blank)
• List formatting (blank lines before/after)
• External links (^ caret for new tabs)

This ensures generated demo content matches real Showroom demo quality instead of generic templates.

I'll create a module with Know/Show structure:

See @showroom/docs/SKILL-COMMON-RULES.md for image syntax and AsciiDoc list formatting rules.

CRITICAL: Content rules (originality, em dashes, Know/Show bullets vs numbers, demo language, talk track): See @showroom/skills/create-demo/references/content-rules.md for all rules with correct/incorrect examples.

Step 10: Final Quality Check (Inline)

The generated module is already in context — check it directly.

Read @showroom/docs/SKILL-COMMON-RULES.md for full quality gate criteria, then verify against this list:

Must fix before delivering (fix silently, note in delivery summary):

| Check | Rule | |---|---| | Know/Show structure | Every section has Know (context) before Show (demonstration) — never Show without Know | | Business value | ROI or outcome framing stated in every Know section | | Presenter notes | At least one [NOTE] or aside block per section with talking points | | No participant steps | Demo is presenter-led — no hands-on exercises requiring participant input | | Headings | Sentence case — not Title Case | | Em dashes | Zero — — rewrite or use -- | | Prohibited terms | No "robust", "powerful", "leverage", "synergy" | | Presenter command blocks | All commands the presenter runs use [source,role="execute"] — not bare [source,bash] | | Code blocks | Config/data blocks use [source,yaml] / [source,json] without role="execute" | | Hardcoded values | No cluster URLs, usernames, passwords — use {user}, {password}, {openshift_console_url} | | Product names | No bare "OCP", "AAP" without first-use expansion |

If anything fails, fix it now. Do not ask the user — just fix and note what was corrected in the delivery summary.

---

Step 11: Update Navigation (REQUIRED)

See @showroom/docs/SKILL-COMMON-RULES.md for navigation update requirements.

---

Step 12: Deliver

CRITICAL: Manage Output Tokens to Prevent Overflow

Write files using Write tool — show brief confirmations only. Keep total output under 5000 tokens.

---

Integration Notes

Templates used (from Showroom repo templates/demo/templates/ or marketplace fallback):

• index.adoc (facilitator/presenter guide)
• 01-overview.adoc, 02-details.adoc
• 03-module-01.adoc (Know/Show structure)
• 99-conclusion.adoc

Quality check at Step 10: Inline — no agents. See Step 10 checklist above.

Files created:

• Demo module: content/modules/ROOT/pages/<module-file>.adoc
• Assets: content/modules/ROOT/assets/images/

Files modified (with permission):

• content/modules/ROOT/nav.adoc - Adds navigation entry

Related Skills

• /showroom:verify-content -- Run quality checks on generated demo content
• /showroom:blog-generate -- Convert demo content into blog posts