athola/skrills / skills/html-portal-generator
html-portal-generator
VerifiedConvert a codebase into a self-contained HTML portal app for ingestion into AI application systems. Produces a single deployable HTML file with embedded CSS, JS, and data.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.8 KB |
SKILL.md
View on GitHub---
name: html-portal-generator
description: Convert a codebase into a self-contained HTML portal app for ingestion into AI application systems. Produces a single deployable HTML file with embedded CSS, JS, and data.
version: 1.0.0
---
# HTML Portal Generator
Convert any codebase into a single, self-contained HTML portal application. The output is one `.html` file with embedded styles, scripts, and data that works offline, on `file://` protocol, and can be uploaded into AI application portals.
## When to Use
- You have a codebase (CLI tool, library, API, framework) and need an interactive HTML representation of its functionality
- The HTML will be uploaded into a smart AI portal or application integration system
- You need all features to work standalone without a running server
- You want users to explore, validate, analyze, and interact with the product from a browser
## Process
Follow these phases in order. Each phase builds on the previous.
### Phase 1: Codebase Analysis
Understand what the product does before writing any HTML.
1. **Read project documentation**: README, CLAUDE.md, architecture docs, changelogs
2. **Identify core crates/packages**: Map each module's purpose and public API
3. **Catalog user-facing features**: CLI commands, API endpoints, configuration options
4. **Extract data structures**: Response types, configuration schemas, enum values
5. **Find existing UI code**: Dashboards, templates, stylesheets (reuse their design language)
Produce a mental inventory:
- Feature list (what the product does)
- Data catalog (what entities/types exist)
- Command/API reference (how users interact)
- Visual identity (colors, fonts, layout patterns from existing UI)
### Phase 2: Reference Analysis (if provided)
If the user provides a reference HTML app:
1. Read the first and last ~3KB to understand structure (large files may be minified)
2. Identify the design pattern: CSS variables, layout system, component structure
3. Note the interaction model: controls bar, status bar, grid layout, tab navigation
4. Extract the color palette and typography from CSS custom properties
### Phase 3: Architecture Design
Design the portal as a single-page app with tab navigation.
**Required structural elements:**
- Sticky header with product name, version badge, and summary stats
- Tab navigation bar for switching between views
- Main container with `max-width` for readability
- Sticky status bar footer with links to docs/repo
- Toast notification system for user feedback
**View planning - map each product feature to a view:**
| Feature Type | View Pattern |
|---|---|
| Entity browsing (skills, packages, endpoints) | Card grid with search/filter/sort and detail panel |
| Validation/checking | Split editor (textarea input) and results panel |
| Analysis/metrics | Input, stat cards, and bar charts |
| Configuration/creation | Form inputs, live preview, and download |
| Format conversion | Side-by-side input/output with target selector |
| Reference docs (commands, APIs) | Searchable/filterable list with copy-on-click |
| Status/compatibility | Matrix grid or table |
| Dashboard/overview | Stat cards, quick actions, and recent items |
**Every view must work 100% standalone.** No external API calls required. Embed demo data. Add optional live-server connection as a bonus.
### Phase 4: Data Embedding
Convert real product data into JavaScript arrays embedded in the HTML.
1. **Scan the actual codebase** for entities (skills, commands, endpoints, types)
2. **Extract metadata** from source files (frontmatter, doc comments, type definitions)
3. **Generate realistic validation states** based on actual product rules
4. **Include failure reasons** as tooltip/detail text so users understand why things pass/fail
5. **Store as `const` arrays** in the `<script>` block - no external JSON files
For large datasets (100+ items), use a build script to extract and format the data rather than hand-writing it.
If the product has local files users might want to scan:
- Add a "Scan Local" button using the File System Access API (`showDirectoryPicker`)
- Walk directories recursively, parse file frontmatter/headers
- Replace the embedded data with live-scanned results
- Store full file content on scanned items for downstream analysis
### Phase 5: Implementation
Build the HTML file following these rules:
**Single-file architecture:**
```
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Product - Portal</title>
<style>/* All CSS here */</style>
</head>
<body>
<!-- All HTML here -->
<script>/* All JS here, wrapped in IIFE */</script>
</body>
</html>
```
**CSS requirements:**
- Use CSS custom properties (`:root { --bg: ...; }`) for theming
- Support dark mode (default) and light mode via `@media (prefers-color-scheme: light)`
- Reuse the product's existing color palette if it has one
- Mobile-responsive with `@media (max-width: ...)` breakpoints
- Style scrollbars, focus states, and transitions
**JavaScript requirements:**
- Wrap everything in an IIFE: `(function() { 'use strict'; ... })();`
- No inline `onclick` handlers - use `addEventListener` exclusively
- Clipboard operations must fall back to `document.execCommand('copy')` for `file://` protocol
- Every click should produce visible feedback (toast, navigation, highlight)
- Autocomplete/datalist for name inputs that reference the embedded data
- Tab navigation via `data-view` attributes and `.active` class toggling
**Interactivity checklist - every element the user can see must do something when clicked:**
- Cards/list items: select, show detail, or navigate
- Buttons: perform action with toast feedback
- Reference items: copy to clipboard on click
- Status indicators: show tooltip with explanation on hover
- External links: open in new tab with `target="_blank" rel="noopener"`
- Quick actions: run in-browser if possible, otherwise copy CLI command and link to docs
### Phase 6: Feature Implementation Patterns
**Entity Browser (the main catalog view):**
```
- Search input (filters by name and description)
- Source/category dropdown filter
- Quality/status dropdown filter
- Sort selector (alpha, by source, by status)
- Card grid with: name, source badge, description, validation tags
- Validation tags with hover tooltips showing failure reasons
- Detail panel (sticky sidebar) with full metadata on click
- Export button (download as JSON)
- Local scan button (File System Access API)
```
**Validator:**
```
- Target selector (individual CLI or "All")
- Textarea for pasting content
- Validate button - runs client-side validation logic
- Autofix button - actually modifies content:
- Fills missing frontmatter fields
- Converts names to kebab-case
- Scaffolds body sections if too short
- Adds target-specific fields (e.g., globs for Cursor)
- Quality score panel (0-100 with visual ring)
- Download button for the validated/fixed file
- Load Sample button with realistic example content
```
**Token/Size Analyzer:**
```
- Name input with datalist autocomplete from catalog
- Load button to pull content from catalog by name
- Textarea for content
- Stat cards: tokens, words, lines, characters
- Progress bar with percentage (label outside bar for small values)
- Size category with color coding
- Optimization suggestions list
```
**Format Converter:**
```
- Source format selector
- Target format selector
- Convert button (single target)
- Convert All button (generates all formats with tab switcher)
- Download button
- Side-by-side input/output layout
```
**Creator/Builder:**
```
- Form fields for metadata (name, description, version, deps)
- Target-specific fields shown/hidden based on selection
- Body textarea with placeholder template
- Live preview panel (pre element)
- File path display showing where to save for each CLI
- Dependency graph visualization
- Download and Send-to-Validator buttons
```
**Reference views (commands, tools, APIs):**
```
- Search input
- Category filter
- Each item shows: name/command, description, usage guidance
- Click to copy, with toast confirmation
- Usage guidance paragraph below each item explaining when/how to use it
```
**Dashboard:**
```
- Stat cards row (total items, categories, etc.)
- Quick Actions panel:
- In-browser actions (green "runs here" badge): actually execute
- CLI-only actions (muted "CLI only" badge): copy command and link to docs
- Supporting info panels with clickable items
- Recent items grid linking to the browser view
```
### Phase 7: Quality Checks
Before delivering, verify:
1. **JS syntax**: `node -e "new Function(scriptContent)"` parses without error
2. **All tabs work**: Each `data-view` has a matching `id="view-..."` element
3. **No emdashes**: Replace all `—` with `-` (AI slop reduction)
4. **No dead clicks**: Every visible element does something on click
5. **Clipboard works on file://**: All copy operations use the `execCommand` fallback
6. **Tooltips on status indicators**: Hover explains why something passed/failed
7. **Responsive**: Views stack on mobile
8. **Open in browser**: `open filename.html` and manually test each tab
### Phase 8: Iteration
The user will test and request changes. Common requests:
- "X doesn't do anything when I click it" - Add click handler with visible feedback
- "Information is missing" - Add data fields, tooltips, or guidance text
- "It should use my actual data" - Scan real files and embed or add local scan
- "Autofix doesn't change anything" - Make it fix more issues, scaffold content
- "The percentage doesn't show" - Move labels outside narrow bars
- "Link to docs" - Add `target="_blank"` links to product documentation
## Output
A single `.html` file (typically 60-120KB) that:
- Works by double-clicking in Finder/Explorer
- Works on `file://` protocol in any browser
- Optionally connects to a live server for real-time data
- Optionally scans local files via browser directory picker
- Can be uploaded directly into AI application portals
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |