| name | oshwhub-readme-skill |
| description | AI Skill for generating product showcase HTML pages for OSHWHUB (立创开源广场) hardware projects. Generates body-only HTML content with inline styles, product-style UI design, image placeholders, BOM tables, and technical documentation sections. Used when users need to create project showcase pages, README pages, or product introduction pages for hardware/electronics projects. Trigger words: "立创开源", "OSHWHUB", "项目展示", "产品介绍", "README生成", "开源项目页面", "硬件项目", "BOM", "原理图", "PCB", "3D外壳" |
| tags | ["OSHWHUB","立创开源","hardware","showcase","README","product-page","BOM","PCB","schematic"] |
| license | MIT |
| compatibility | Works with any AI Agent supporting skill loading; generates static HTML for browser rendering |
| metadata | {"author":"Claude","version":"1.0.0"} |
oshwhub-readme-skill
AI Skill for generating beautiful product showcase HTML pages for OSHWHUB hardware projects. Follows the design style of professional product introduction pages with inline CSS, gradient backgrounds, card layouts, and responsive grids.
Core Rules
- Body content only — Generate only the HTML content that goes inside
<body>. No <!DOCTYPE>, <html>, <head>, or <body> tags
- No
<style> or <script> tags — All styling must be inline style="" attributes
- No blank lines — Output must be continuous HTML with no empty lines between elements
- Image matching by filename — Scan the
img/ folder and match images to sections based on descriptive text in filenames. No fixed naming convention required
- Read before generate — Must read user's source code (
code/), BOM table and netlist (SRC/) before generating the page
- Section-by-section HTML — Do NOT generate the entire HTML at once. Generate and write each section individually to
index.html
- Project capabilities inquiry — Auto-infer project capabilities from scanned files. Only ask the user to confirm uncertain items
Workflow
Step 1: Scan and Read User Files (Must execute first)
Before collecting information or generating the page, you must scan and read the user's prepared files first:
- Scan
img/ folder: Use Glob to list all image files under img/ (*.png, *.jpg, *.jpeg, *.gif, *.webp, *.svg)
- Read
code/ folder: Use Glob and Read to scan source file structure under code/, read key file contents (e.g., main.cpp, main.ino, config.h, platformio.ini, CMakeLists.txt, etc.)
- Read BOM in
SRC/ folder: Use Glob to find BOM files under SRC/ (*BOM*, *bom*, .csv or .xlsx), use Read to parse content into table data
- Read netlist in
SRC/ folder: Use Glob to find netlist files (*.enet), use Read to parse the JSON content. EasyEDA netlist files use .enet suffix and are in JSON format
⚠️ If a folder does not exist, skip the corresponding step. Never assume files exist — always scan first.
Step 2: Match Images by Filename Description
Match images found in img/ to page sections based on descriptive text in filenames. Use the following keyword matching rules:
| Target Section | Filename Keywords (case-insensitive) |
|---|
| Hero | hero, 主图, 渲染, 产品, 正面, 效果图, 展示, main, render, product, front |
| Composition | composition, 组成, 架构, 框图, 模块图, 系统, architecture, block, diagram, system |
| Feature Details | feature, 功能, 特性, 演示, 效果, 截图, 蓝牙, WiFi, 显示, 遥控, 传感, demo, bluetooth, display, remote, sensor |
| PCB Design | pcb, PCB, 布局, 板图, 设计图, layout |
| Schematic | schematic, 原理图, 电路图, 电路, circuit |
| 3D Shell Front | 3d, 3D, 外壳, 壳体, 正面, 底壳, enclosure, shell, case, bottom |
| 3D Shell Back | 背面, 顶壳, top, back |
| 3D Exploded | 爆炸, 拆解, 分解, exploded, assembly view |
| Assembly | assembly, 组装, 装配, 成品, 实物, real, photo |
| Pin Definition | pinout, 引脚, 接口, 排针, pin |
| BOM Related | bom, BOM, 元器件, 物料, 清单, component |
Matching logic:
- Iterate through each file in
img/, check if the filename (without extension) contains any of the above keywords
- Each file can only match one section; prioritize more specific keywords (e.g., "schematic" over "circuit")
- Unmatched images are not used, but should be listed in the report for user confirmation
- If multiple images match the same section, use the most recently modified file
Step 3: Gather Project Information
Based on file content read in Step 1, collect remaining information via AskUserQuestion. Do not ask again for information already obtained from files:
- Project name — The display name of the project
- Project subtitle — A one-line description/tagline
- Project type — Hardware project type (e.g., development board, sensor module, IoT device, tool)
- Has schematic? — Whether the project has a schematic (auto-confirm if schematic image matched in
img/)
- Has PCB? — Whether the project has a PCB (auto-confirm if PCB image matched in
img/)
- Has code? — Whether the project has code (auto-confirm if source files found in
code/)
- Has 3D shell? — Whether the project has a 3D shell (auto-confirm if 3D-related images matched in
img/)
- Key features — List of main feature modules (can be inferred from source comments or file structure, still need user confirmation)
- Main MCU/chip — The primary microcontroller or chip (if inferable from source code, pre-fill and confirm)
- BOM data — If BOM already read from
SRC/, use automatically; otherwise ask the user
Step 4: Create Directory Structure
project-root/
├── img/ # User has placed images here
├── code/ # User has placed source code here
├── SRC/ # EasyEDA netlist and BOM (if schematic+PCB)
└── index.html # Generated showcase page
Ensure img/ and code/ folders exist (create if not). If user confirms schematic+PCB, ensure SRC/ folder exists.
Step 5: Generate HTML Section by Section
Do NOT generate the entire HTML at once. Follow the order below, generate each section individually and append to index.html:
Write Strategy
- Use Write tool to create
index.html, write the outermost wrapper div opening tag
- For each section, use Edit tool to append that section's HTML to the end of the file
- Each section is generated independently, then written to the file
- After all sections are written, append the outer wrapper closing tag
Section Generation Order
| Order | Section | Description |
|---|
| 1 | Outer Wrapper Start | <div style="color-scheme:light;font-family:..."> + <div style="max-width:1100px;..."> |
| 2 | Hero Section | Gradient background with project name and subtitle |
| 3 | Composition/Overview | Project architecture overview |
| 4 | Feature Details | Feature descriptions (generate each feature module as a sub-section) |
| 5 | Hardware Details | Hardware documentation (if has PCB) |
| 6 | 3D Shell | 3D shell showcase (if has 3D shell) |
| 7 | BOM Table | Component list (generated from BOM data read from SRC/) |
| 8 | Quick Start | Quick start guide (if has code) |
| 9 | Source Code | Source code introduction (generated from structure read from code/) |
| 10 | Related Links | Related resource links |
| 11 | Outer Wrapper End | </div></div> |
Section-by-Section Write Example
Step 5.1: Write outer wrapper opening tag → index.html
Step 5.2: Generate Hero Section → Edit append to index.html
Step 5.3: Generate Composition Section → Edit append to index.html
Step 5.4: Generate Feature Section → Edit append to index.html (each feature module appended sequentially)
...
Step 5.N: Edit append outer wrapper closing tag
⚠️ When appending, ensure there are no blank lines between new content and existing content.
HTML Template Structure
The page is organized into these sections (include only relevant sections based on project type):
1. Hero Section
Gradient background with project name and subtitle. Purple/blue theme.
2. Composition/Overview Section
Block diagram showing project architecture. Two-column layout for hardware vs software modules.
3. Feature Details Section
For each major feature module:
- Section header with colored accent bar
- Two-column grid: description card + image card
- Feature list with bullet points
4. Hardware Details Section (if has PCB)
- Hardware overview with 4-column module grid
- Detailed module descriptions with LCSC part numbers
- Pin definition table
5. 3D Shell Section (if has 3D shell)
- Three-column part overview (bottom shell, top shell, button caps)
- Individual part details with images
6. BOM Section
- Responsive table with columns: #, Name, Description, Qty, Designator, LCSC
7. Quick Start Section
- Three-step numbered cards (environment setup, build/flash, verify)
- Notes/warnings box
8. Source Code Section (if has code)
- Code folder structure overview
- Key files description
- Build instructions
9. Related Links Section
- Link cards to related resources
Design Style Reference
All inline styles must follow this design language:
Color Palette
- Primary purple:
#7c3aed / #a855f7
- Primary green:
#059669 / #34d399
- Primary blue:
#2563eb / #60a5fa
- Primary orange:
#ea580c / #fb923c
- Primary yellow:
#ca8a04 / #fbbf24
- Primary red:
#dc2626 / #f87171
- Text dark:
#0f0c29
- Text muted:
#64748b
- Light bg:
#ffffff / #f8fafc
- Border:
#e2e8f0
Dark Mode Support
Use light-dark() CSS function for color values:
color: light-dark(#0f0c29, #ffffff)
background: light-dark(#ffffff, #1e293b)
Card Style
background: linear-gradient(160deg, light-dark(#ffffff,#1e293b), light-dark(#f8fafc,#0f172a));
border: 1px solid light-dark(#e2e8f0,#1e293b);
border-radius: 18px;
padding: 32px;
box-shadow: light-dark(0 2px 12px rgba(0,0,0,0.05), none);
Section Header Badge
display: inline-block;
font-size: 12px;
font-weight: 800;
color: light-dark(#722ed1,#a78bfa);
background: light-dark(rgba(114,46,209,0.08),rgba(114,46,209,0.12));
padding: 8px 20px;
border-radius: 20px;
margin-bottom: 16px;
letter-spacing: 2px;
Section Title
font-size: 38px;
font-weight: 900;
color: light-dark(#0f0c29,#f1f5f9);
margin: 0 0 12px;
Accent Bar (before subsection titles)
display: inline-block;
width: 6px;
height: 28px;
background: linear-gradient(180deg, #7c3aed, #a855f7);
border-radius: 3px;
Feature Item Style
display: flex;
align-items: flex-start;
gap: 10px;
With colored dot:
display: inline-block;
min-width: 8px;
height: 8px;
border-radius: 50%;
background: #7c3aed;
margin-top: 7px;
Image Style
width: 100%;
border-radius: 12px;
margin-bottom: 48px;
Container
max-width: 1100px;
margin: 0 auto;
padding: 0 36px;
Outer Wrapper
color-scheme: light;
font-family: -apple-system, BlinkMacSystemFont, ...;
Section Templates
Hero Section Template
<div style="background:linear-gradient(135deg,light-dark(#f5f0ff,#1a0533) 0%,light-dark(#e8dfff,#302b63) 40%,light-dark(#ffffff,#0a0a1a) 100%);padding:100px 40px 80px;text-align:center;overflow:hidden"><div style="top:-200px;right:-200px;width:600px;height:0px;border-radius:50%;background:radial-gradient(circle,rgba(114,46,209,light-dark(0.12,0.2)),transparent 60%);filter:blur(40px)"></div><div style="bottom:-150px;left:-100px;width:500px;height:0px;border-radius:50%;background:radial-gradient(circle,rgba(99,102,241,light-dark(0.08,0.15)),transparent 60%);filter:blur(40px)"></div><div style="z-index:1">
<h1 style="font-size:52px;font-weight:900;color:light-dark(#0f0c29,#ffffff);margin:0 0 16px;letter-spacing:-1px">{{PROJECT_NAME}}</h1><p style="font-size:15px;color:light-dark(#7a6a8a,rgba(255,255,255,0.45));margin:0">{{PROJECT_SUBTITLE}}</p></div></div>
Section Wrapper Template
<div style="padding:72px 0 48px;border-top:1px solid light-dark(#e2e8f0,#1e293b)">
<div style="text-align:center;margin-bottom:56px"><div style="display:inline-block;font-size:12px;font-weight:800;color:light-dark({{BADGE_COLOR_DARK}},{{BADGE_COLOR_LIGHT}});background:light-dark({{BADGE_BG_DARK}},{{BADGE_BG_LIGHT}});padding:8px 20px;border-radius:20px;margin-bottom:16px;letter-spacing:2px">{{BADGE_TEXT}}</div><h2 style="font-size:38px;font-weight:900;color:light-dark(#0f0c29,#f1f5f9);margin:0 0 12px">{{SECTION_TITLE}}</h2><p style="font-size:16px;color:light-dark(#64748b,#94a3b8);margin:0;max-width:640px;margin-left:auto;margin-right:auto;line-height:1.8">{{SECTION_DESC}}</p></div>
{{SECTION_CONTENT}}
</div>
Two-Column Feature Grid Template
<div style="display:grid;grid-template-columns:1fr 1fr;gap:24px;margin-bottom:48px">
<div style="background:linear-gradient(160deg,light-dark(#ffffff,#1e293b),light-dark(#f8fafc,#0f172a));border:1px solid light-dark(#e2e8f0,#1e293b);border-radius:18px;padding:32px;box-shadow:light-dark(0 2px 12px rgba(0,0,0,0.05),none)">
<div style="font-weight:800;font-size:18px;color:light-dark(#0f0c29,#f1f5f9);margin-bottom:16px;display:flex;align-items:center;gap:10px"><span style="font-size:22px">{{ICON}}</span>{{CARD_TITLE}}</div>
<div style="color:light-dark(#64748b,#94a3b8);font-size:14px;line-height:2">
{{FEATURE_LIST}}
</div>
</div>
<div style="background:linear-gradient(160deg,light-dark(#ffffff,#1e293b),light-dark(#f8fafc,#0f172a));border:1px solid light-dark(#e2e8f0,#1e293b);border-radius:18px;padding:32px;box-shadow:light-dark(0 2px 12px rgba(0,0,0,0.05),none)">
{{SECOND_CARD_CONTENT}}
</div>
</div>
BOM Table Row Template
<div style="display:flex;padding:10px 0;border-bottom:1px solid light-dark(#f1f5f9,#1e293b);min-width:600px;align-items:center{{ROW_BG}}"><div style="flex:0.4;text-align:center;font-size:13px;color:light-dark(#94a3b8,#475569)">{{INDEX}}</div><div style="flex:1.5;font-size:13px;font-weight:600;color:light-dark(#0f0c29,#f1f5f9)">{{NAME}}</div><div style="flex:1;font-size:13px;color:light-dark(#64748b,#94a3b8)">{{DESC}}</div><div style="flex:0.4;font-size:13px;color:light-dark(#0f0c29,#f1f5f9);text-align:center">{{QTY}}</div><div style="flex:0.8;font-size:13px;color:light-dark(#94a3b8,#475569);font-family:monospace">{{DESIGNATOR}}</div><div style="flex:0.8;font-size:13px;color:#7c3aed;font-weight:600">{{LCSC}}</div></div>
Quick Start Step Template
<div style="flex:1;min-width:240px;max-width:300px;background:linear-gradient(160deg,light-dark(#ffffff,#111827),light-dark(#f8fafc,#0f172a));border:1px solid light-dark(#e2e8f0,#1e293b);border-radius:18px;padding:32px 24px;text-align:center;box-shadow:light-dark(0 1px 3px rgba(0,0,0,0.06),none)"><div style="width:52px;height:52px;border-radius:50%;background:linear-gradient(135deg,{{GRADIENT_START}},{{GRADIENT_END}});color:#fff;display:flex;align-items:center;justify-content:center;margin:0 auto 16px;font-size:22px;font-weight:900">{{STEP_NUM}}</div><div style="font-size:17px;font-weight:800;color:light-dark(#0f0c29,#f1f5f9);margin-bottom:8px">{{STEP_TITLE}}</div><div style="color:light-dark(#64748b,#94a3b8);font-size:13px;line-height:1.8">{{STEP_DESC}}</div></div>
Note/Warning Box Template
<div style="background:linear-gradient(160deg,light-dark(#fef3c7,#78350f),light-dark(#fffbeb,#451a03));border:1px solid light-dark(#fde68a,#92400e);border-radius:14px;padding:24px 28px">
<div style="font-weight:800;color:light-dark(#92400e,#fde68a);margin-bottom:12px;font-size:15px">{{NOTE_TITLE}}</div>
<div style="color:light-dark(#a16207,#fbbf24);font-size:14px;line-height:2">{{NOTE_CONTENT}}</div>
</div>
Output Requirements
- Section-by-section writing — Generate and write each section to
index.html individually, one section at a time
- No blank lines between written HTML segments; the final result must be a continuous HTML block
- All
style attributes must use the exact syntax from the templates (no spaces after colons in shorthand properties)
- Every
<img> tag must have style="width:100%;border-radius:12px;margin-bottom:48px" or similar appropriate styling
- The outermost wrapper must include
color-scheme:light;font-family:-apple-system,BlinkMacSystemFont,
- Section separators use
border-top:1px solid light-dark(#e2e8f0,#1e293b)
- Image source —
<img> src must use the actual filename from img/, not placeholder names
Example Usage
User: "Generate a showcase page for my open-source project"
Execution Flow
- Scan files — Use Glob to scan
img/, code/, SRC/ folders; Read to load key files
- Match images — Match images in
img/ to sections based on descriptive text in filenames
- Collect info — Based on read files, use AskUserQuestion to only ask for missing information
- Generate section by section — Generate HTML and write to
index.html section by section:
- Write outer wrapper opening tag
- Generate and append each section (Hero → Composition → Features → Hardware → BOM → Quick Start → Source Code → Links)
- Write outer wrapper closing tag
- Output summary — Report to user which images were used, BOM data source, and which sections were generated
Image Usage Report Format
After generating HTML, provide a usage report to the user:
This generation used the following resources:
[Matched and Used]
✅ ESP32 Smart Car Front Render.png → Hero section
✅ Project Architecture Diagram.png → Composition section
✅ Bluetooth Remote Control Demo.png → Feature Details - Bluetooth Remote
[Unmatched - Please Check Naming]
⚠️ IMG_20240101.png — Unable to identify purpose, please rename with descriptive text
[Missing Sections]
❌ Hardware Details — No PCB/schematic images found
❌ 3D Shell — No 3D shell images found
💡 Unmatched images can be renamed and the Skill re-run. Matched images do not need changes.
