knowledge-hub-create

name

knowledge-hub-create

description

Create a comprehensive multi-page HTML knowledge hub website for any product or technology, sourcing content from Google Docs, GitHub repos, Jira, Slack, and local docs. Use when the user wants to build a product information site, knowledge base, documentation hub, or "everything you need to know" site for a product, component, or technology. Also use when the user says "create a knowledge site", "build a product hub", "make an info site", "I need a product knowledge base", or references creating something similar to the MCP Gateway Knowledge Hub (RHCL site).

Knowledge Hub Creator

Create comprehensive, multi-page HTML knowledge hub websites for any product or technology. The hub aggregates information from multiple sources (Google Docs, GitHub repos, Jira, Slack, local docs, transcripts) into a well-organized, cross-referenced documentation site with Red Hat branding, deployed to GitHub Pages.

Reference Implementation

The MCP Gateway Knowledge Hub at mcps/mcp-gateway/RHCL/ is the reference implementation. Study it for:

• Design tokens and visual style: mcps/mcp-gateway/RHCL/styles.css
• Navigation system: mcps/mcp-gateway/RHCL/nav.js
• Page structure: Any HTML page in the hub (e.g., understand/what-is-it.html)
• Content patterns: Feature cards, callout boxes, status tables, flow diagrams, badges
• Design spec: docs/superpowers/specs/2026-06-21-mcp-gateway-knowledge-hub-design.md
• Implementation plan: docs/superpowers/plans/2026-06-21-mcp-gateway-knowledge-hub.md

When to Use

• User wants a comprehensive product knowledge site
• User wants to consolidate scattered information about a product/technology
• User says "build me a site like the gateway hub" or "create a knowledge base for X"
• User needs a single place to understand, sell, build, govern, or plan a product

Preconditions

The following tools and access are needed:

• Google Workspace MCP — for fetching Google Docs (user email: [e-mail])
• Slack MCP — for searching Slack channels
• Playwright MCP — for visual verification of the built site
• GitHub CLI (gh) — for checking repo releases/state
• Jira API — env vars: JIRA_USER, JIRA_TOKEN, JIRA_SERVER
• Git — for commits and GitHub Pages deployment

If any source is unavailable, the skill should proceed with available sources and note the gap.

Workflow

The skill follows a 9-phase workflow. Each phase must complete before the next begins.

Phase 1: Discovery & Clarification
  ↓
Phase 2: Source Inventory
  ↓
Phase 3: Site Design (Brainstorming)
  ↓
Phase 4: Implementation Planning
  ↓
Phase 5: Source Verification Sweep
  ↓
Phase 6: Scaffolding (CSS + JS)
  ↓
Phase 7: Content Creation (HTML pages)
  ↓
Phase 8: Quality Assurance
  ↓
Phase 9: Deployment & Maintenance Skill

---

Phase 1: Discovery & Clarification

Goal: Understand what the user wants to build and for whom.

Ask clarifying questions ONE AT A TIME if not already answered in the initial request:

1. Product/technology: What product or technology is this hub about?
2. Audience: Who is the primary reader? (PM, engineer, sales, executive, customer?)
   • This determines the tone: PMs need analogies and progressive detail; engineers need code and CRDs; sales needs talk tracks and competitive positioning.
3. Knowledge level: How well does the audience understand the domain? (e.g., "I don't understand networking well" means explain concepts from first principles)
4. Output location: Where should the site live in the repo? (e.g., mcps/mcp-gateway/RHCL/)
5. Deployment: Should it deploy to GitHub Pages? If so, what's the base URL?
6. Intention: What does the user want to DO with this information? Common patterns:
   • Understand the product deeply
   • Sell it to customers (talk tracks, competitive)
   • Build with it (deployment, configuration)
   • Govern it (ecosystem, dependencies, lifecycle)
   • Plan for it (roadmap, gaps, decisions)
   • All of the above (full knowledge hub)

Phase 2: Source Inventory

Goal: Identify all available information sources.

Ask the user about each source type and scan the repo for existing content:

Source Type	How to Find	Tool
Local docs	Glob for docs/knowledge-review/**/*{product}*, docs/starting-artifacts/**/*, transcripts	Glob, Read
Google Docs	Ask user for doc IDs, or search Drive	Google Workspace MCP
GitHub repos	Ask user for upstream repos	gh CLI
Jira tickets	Ask user for key tickets/epics	Jira REST API
Slack channels	Check docs/slack-channels.md for relevant channels, then confirm with user	Slack MCP
Transcripts	Glob for **/transcripts/**/*	Glob, Read
Existing presentations	Glob for **/*.html in the product area	Glob, Read
Blog posts	Ask user, or search Red Hat blog	WebFetch
PDFs	Glob for **/*.pdf in the product area	Read (with pages param)

Build a source inventory document listing every source found, its type, and a brief description of what it contains.

Phase 3: Site Design (Brainstorming)

Goal: Design the site structure collaboratively with the user.

Use the superpowers:brainstorming skill. Key decisions to make:

1. Navigation model — Role-based (recommended: organized by what the user needs to DO) vs. component-centric vs. audience-centric

2. Sections — Which sections does the hub need? The MCP Gateway hub used:

   • Understand It (concepts, architecture, security basics)
   • Sell It (value prop, customer stories, competitive)
   • Build It (deployment, configuration, features)
   • Govern It (ecosystem, dependencies, lifecycle)
   • Plan It (roadmap, gaps, open questions, pricing)
   • Quick Reference (external links)

   Not all products need all sections. Tailor to the audience and intention.

3. Pages within each section — What specific pages are needed?

4. Visual design — Use the Red Hat dark theme from the reference implementation unless the user requests otherwise.

5. Content patterns — Which patterns are needed? (feature cards, callout boxes, status tables, flow diagrams, comparison tables, customer quotes)

Output: A design spec saved to docs/superpowers/specs/YYYY-MM-DD-{product}-knowledge-hub-design.md

Phase 4: Implementation Planning

Goal: Break the build into tasks.

Use the superpowers:writing-plans skill. Standard task decomposition:

1. Source verification sweep — Fetch all live sources, compare against local docs, compile verified data
2. Shared CSS — Copy and adapt styles.css from reference implementation (or reuse it directly if in the same repo)
3. Navigation JS — Copy and adapt nav.js with the new site map (or reuse with config)
4. Landing page — Create index.html with hero, section cards, what's new
5. Content sections — One task per section (each creates 3-5 pages)
6. Quick Reference — External links page
7. Link verification + cleanup — Verify all inter-page links work
8. Maintenance skill — Create an update/refresh skill (optional but recommended)
9. Deployment — Push to GitHub Pages

Output: An implementation plan saved to docs/superpowers/plans/YYYY-MM-DD-{product}-knowledge-hub.md

Phase 5: Source Verification Sweep

Goal: Verify all facts are current before writing content.

For each source in the inventory:

Source	Verification Method
Google Docs	mcp__google-workspace__get_doc_as_markdown — read current version, extract key facts
GitHub repos	gh api repos/{owner}/{repo}/releases/latest — check versions, release dates
Jira tickets	curl -s -u "$JIRA_USER:$JIRA_TOKEN" "$JIRA_SERVER/rest/api/3/issue/{KEY}" — check status
Slack channels	mcp__slack__get_channel_history — scan last 2 weeks for updates
Local docs	Read and cross-reference against live sources

Output: A _source-verification.md file in the output directory with sections for versions, features, roadmap, gaps, and discrepancies.

Rule: Where live sources disagree with local docs, the live source wins.

Phase 6: Scaffolding (CSS + JS)

Goal: Create the shared stylesheet and navigation.

Option A — Reuse from reference (recommended if in the same repo):

• Copy mcps/mcp-gateway/RHCL/styles.css to the new output directory
• Adapt nav.js with the new SITE_MAP matching the designed page structure
• The CSS is generic enough to work for any hub

Option B — Fresh build (if different repo or different visual style):

• Create styles.css with design tokens from the spec
• Create nav.js with the site map and path handling

Critical CSS rules learned from the MCP Gateway build:

• HTML pages use id="hub-header" and id="hub-sidebar" — CSS must have both ID and class selectors (#hub-header, .hub-header)
• Sidebar <ul> elements need list-style: none; margin: 0; padding: 0 on both the nav and nested lists
• html, body must have overflow: auto (not hidden) for scrollable pages
• Path detection in nav.js must handle both file:/// and GitHub Pages paths

Phase 7: Content Creation (HTML pages)

Goal: Create all content pages with verified, sourced content.

For each page:

1. Read all relevant source documents before writing any content
2. Use the HTML template:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>[Page Title] — [Hub Name]</title>
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
  <link href="https://fonts.googleapis.com/css2?family=Red+Hat+Display:wght@400;500;600;700;800;900&family=Red+Hat+Mono:wght@400;500;600&family=Red+Hat+Text:wght@400;500;600;700&display=swap" rel="stylesheet">
  <link rel="stylesheet" href="[../]styles.css">
</head>
<body>
  <div class="hub-layout">
    <header id="hub-header"></header>
    <aside id="hub-sidebar"></aside>
    <main class="hub-main">
      <!-- PAGE CONTENT -->
      <footer class="page-footer" data-verified="YYYY-MM-DD">
        <div class="staleness-indicator"></div>
        <div class="footer-sources"><h4>Sources</h4><ul></ul></div>
        <div class="related-pages"><h4>Related Pages</h4><ul></ul></div>
      </footer>
    </main>
  </div>
  <script src="[../]nav.js"></script>
</body>
</html>

3. Use ../ prefix for pages in subdirectories, ./ for root-level pages
4. Apply content patterns from styles.css:
   • .callout--insight (teal) for key insights
   • .callout--gap (orange) for gaps and warnings
   • .callout--quote (purple) for customer/stakeholder quotes
   • .callout--source (muted) for source citations
   • .feature-card + .badge--shipped/.badge--tp/.badge--planned/.badge--gap for feature status
   • .flow-diagram + .flow-step + .flow-arrow for process flows
   • .status-table for comparison/status tables
5. Attribute every claim to a source document with meeting date and speaker name where applicable
6. Include footer with data-verified date, source links, and related pages

Content tone guidelines by audience:

• PM audience: Use analogies first, then plain language, then technical detail. Progressive depth.
• Engineer audience: Lead with technical detail, include code examples and CRD YAML.
• Sales audience: Lead with business value, include talk tracks and competitive tables.
• Executive audience: Lead with strategic positioning, include market context.

Parallelization: Content sections are independent — use superpowers:subagent-driven-development to dispatch one subagent per section for faster builds. Each subagent gets:

• The section's page list and content requirements from the design spec
• All relevant source documents to read
• The HTML template and CSS class reference
• The verified data from _source-verification.md

Phase 8: Quality Assurance

Goal: Verify the site works correctly.

1. Start a local HTTP server: python -m http.server 8765 from the output directory
2. Visual verification with Playwright:
   • Navigate to each section's landing page
   • Take screenshots of key pages
   • Verify: sidebar renders, navigation works, content displays, no layout breaks
3. Link verification:

   cd {output_dir}
   grep -roh 'href="[^"]*\.html[^"]*"' *.html */*.html 2>/dev/null | sort -u
   

   Check each target file exists. Fix broken links.
4. Content spot-check: Pick 3 pages, verify version numbers and dates match _source-verification.md

Phase 9: Deployment & Maintenance Skill

Goal: Deploy the site and create a refresh mechanism.

1. Commit all files: One commit per logical unit (CSS, JS, landing, each section, reference)
2. Push to GitHub Pages: git push origin main
3. Verify deployment: Check GitHub Actions workflow completes, then navigate to the live URL
4. Create maintenance skill (optional but recommended):
   • Create .claude/skills/update-{product}-hub/SKILL.md
   • The skill should sweep the same sources from Phase 5 and update stale pages
   • Include hardcoded source IDs (Google Doc IDs, repo names, Jira keys, Slack channels) so the agent doesn't have to search for them
   • Every page has a data-verified date in its footer; the skill updates this on refresh

Reusable Components

These files from the reference implementation can be reused or adapted:

File	Reuse Strategy
styles.css	Copy as-is — design tokens and content patterns are generic
nav.js	Copy and replace the SITE_MAP constant with the new site's pages
HTML template	Copy the boilerplate, fill with new content
Update skill	Copy .claude/skills/update-gateway-hub/SKILL.md and replace source IDs

Idempotency

Safe to run multiple times for the same product. Subsequent runs will:

• Re-verify sources and update stale content
• Overwrite existing HTML pages with fresh content
• Preserve the site structure and styling

Error Handling

Situation	Action
Google Doc inaccessible	Note the gap, proceed with other sources, flag in the site's content
Jira API auth failure	Ask user to check JIRA_USER/JIRA_TOKEN env vars
Slack channel not found	Ask user for correct channel name
GitHub repo not found	Ask user for correct repo owner/name
Conflicting information	Present both versions to user, ask which to use
Transient network error	Retry once, then skip and note the gap

Example Invocation

User: Create a knowledge hub for the MCP Lifecycle Operator, similar to what we built for the Gateway.

AI: I'll create a knowledge hub for MCPLO. Let me start by understanding the scope...
[Phase 1: asks about audience, sources, deployment]
[Phase 2: scans repo for MCPLO docs, transcripts, presentations]
[Phase 3: designs the site structure collaboratively]
[Phase 4: breaks into implementation tasks]
[Phase 5-9: builds, verifies, deploys]