commit 955439d1331cb7c0412f0a12232cc1b2db4bfa40 Author: James Gong Date: Wed Jan 14 16:22:37 2026 +1100 Initial commit: Xiaohongshu Images Skill - Add SKILL.md with complete skill definition - Add default HTML/CSS prompt template for styled article pages - Add Gemini API image generation script for cover images - Add Playwright screenshot script with 3:4 ratio capture - Add .env.example and .gitignore configuration Co-Authored-By: Claude Opus 4.5 diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..2ab2c3e --- /dev/null +++ b/.env.example @@ -0,0 +1,17 @@ +# Xiaohongshu Images Skill - Environment Configuration +# +# Instructions: +# 1. Copy this file to .env +# 2. Fill in your API key +# 3. The .env file is gitignored and will not be committed to version control +# +# ============================================================================ + +# ============================================================================ +# Image Generation Configuration +# ============================================================================ + +# Google Gemini API Key +# Obtain from: https://aistudio.google.com/app/apikey +# Used for generating cover images with AI +GEMINI_API_KEY=your_gemini_api_key_here diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..0ec37f4 --- /dev/null +++ b/.gitignore @@ -0,0 +1,65 @@ +# Environment variables (contains API keys, should not be committed) +.env +.env.local +.env.*.local + +# Output directory (generated content) +output/ + +# Python +__pycache__/ +*.py[cod] +*$py.class +*.so +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +*.egg-info/ +.installed.cfg +*.egg + +# Virtual environments +venv/ +ENV/ +env/ +.venv/ + +# IDE and editors +.idea/ +.vscode/ +*.swp +*.swo +*.sublime-workspace +*.sublime-project + +# macOS +.DS_Store +.AppleDouble +.LSOverride +._* + +# Windows +Thumbs.db +ehthumbs.db +Desktop.ini + +# Playwright +.playwright-mcp/ + +# Temporary files +*.tmp +*.temp +*.log + +# Package artifacts +*.skill diff --git a/README.md b/README.md new file mode 100644 index 0000000..7c15d05 --- /dev/null +++ b/README.md @@ -0,0 +1,208 @@ +# Xiaohongshu Images Skill + +A Claude Code skill that transforms markdown, HTML, or text content into beautifully styled HTML pages with AI-generated cover images, then captures them as sequential screenshots at 3:4 ratio for Xiaohongshu posting. + +## Features + +- **Content Processing**: Accepts markdown, HTML, or plain text content +- **AI Cover Images**: Generates editorial-style cover illustrations using Google Gemini +- **Styled HTML Output**: Creates beautifully formatted HTML pages with modern typography +- **Screenshot Capture**: Takes sequential 3:4 ratio screenshots optimized for Xiaohongshu +- **Smart Text Boundaries**: Ensures no text is cut off in screenshots + +## Installation + +### Prerequisites + +- Python 3.8 or higher +- Claude Code CLI + +### Setup + +1. **Clone or copy this skill to your Claude skills directory:** + +```bash +# Copy to global skills +cp -r xiaohongshu-images-skill ~/.claude/skills/ + +# Or symlink for development +ln -s /path/to/xiaohongshu-images-skill ~/.claude/skills/xiaohongshu-images-skill +``` + +2. **Install Python dependencies:** + +```bash +pip install python-dotenv playwright +playwright install chromium +``` + +3. **Configure environment variables:** + +```bash +cd ~/.claude/skills/xiaohongshu-images-skill +cp .env.example .env +# Edit .env and add your GEMINI_API_KEY +``` + +4. **Get your Gemini API Key:** + +Visit [Google AI Studio](https://aistudio.google.com/app/apikey) to obtain your API key. + +## Usage + +### Via Claude Code + +Invoke the skill in Claude Code: + +``` +/xiaohongshu-images +``` + +Then provide your content: +- Paste markdown/HTML content directly +- Provide a file path: `/path/to/article.md` +- Provide a URL to fetch content from + +### Example + +```markdown +/xiaohongshu-images + +# My Article Title + +This is the introduction paragraph explaining the topic... + +## Section 1 + +Content for section 1 with detailed explanation... + +## Section 2 + +More content here with examples... +``` + +### Output + +The skill generates: +- `output//index.html` - Styled HTML page +- `output//images/cover.png` - AI-generated cover image +- `output//screenshots/01.png, 02.png, ...` - Sequential screenshots + +## Directory Structure + +``` +xiaohongshu-images-skill/ +├── SKILL.md # Main skill definition +├── README.md # This file +├── prompts/ +│ └── default.md # Default HTML/CSS styling prompt +├── scripts/ +│ ├── generate_images.py # Gemini image generation +│ └── screenshot.py # Screenshot capture +├── output/ # Generated outputs (gitignored) +├── .env # Environment variables (gitignored) +├── .env.example # Environment template +└── .gitignore +``` + +## Customization + +### Custom Prompt Templates + +Create custom styling templates in the `prompts/` directory: + +1. Create a new `.md` file (e.g., `prompts/minimal.md`) +2. Define your HTML/CSS specifications +3. Invoke with: "Use the minimal template for this article" + +### Modifying Styles + +Edit `prompts/default.md` to customize: +- Card dimensions and colors +- Font families and sizes +- Typography hierarchy +- Code block styling +- Responsive breakpoints + +## Configuration + +### Environment Variables + +| Variable | Description | Required | +|----------|-------------|----------| +| `GEMINI_API_KEY` | Google Gemini API key for image generation | Yes | + +### Screenshot Settings + +Default screenshot dimensions (3:4 ratio for Xiaohongshu): +- Width: 1080px +- Height: 1440px +- Scale factor: 2x (Retina quality) + +To modify, edit `scripts/screenshot.py`: +```python +SCREENSHOT_WIDTH = 1080 +SCREENSHOT_HEIGHT = 1440 +``` + +## Scripts + +### generate_images.py + +Generates cover images using Google Gemini API. + +```bash +python scripts/generate_images.py output//prompts.json +``` + +JSON format: +```json +{ + "theme": "Article theme for cover image generation" +} +``` + +### screenshot.py + +Captures sequential screenshots of HTML pages. + +```bash +python scripts/screenshot.py output//index.html +``` + +Features: +- Automatic page scrolling +- Smart text boundary detection +- No text cut-off at boundaries +- 3:4 aspect ratio output + +## Troubleshooting + +### Gemini API Issues + +- Verify your API key is correctly set in `.env` +- Check API quotas at [Google AI Studio](https://aistudio.google.com/) +- Ensure the API key has access to image generation models + +### Screenshot Issues + +- Install Playwright browsers: `playwright install chromium` +- Check file paths are correct +- Ensure HTML file is valid and accessible + +### Font Loading + +If fonts don't load in screenshots: +- Increase wait time in `screenshot.py` +- Check Google Fonts availability +- Consider using local fonts + +## License + +MIT License - See LICENSE file for details. + +## Related Skills + +- `chinese-viral-writer` - Chinese viral content creation +- `wechat-article-formatter` - WeChat article formatting +- `wechat-article-publisher` - WeChat publishing automation diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..b09ada7 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,267 @@ +--- +name: xiaohongshu-images +description: Generate beautifully styled HTML pages from markdown/HTML/txt content with cover images using Gemini AI, then capture screenshots at 3:4 ratio for Xiaohongshu. Use when user wants to create styled article pages, generate article images, or prepare content for Xiaohongshu platform. +--- + +# Xiaohongshu Images Skill + +This skill transforms markdown, HTML, or text content into beautifully styled HTML pages with AI-generated cover images, then captures them as sequential screenshots at 3:4 ratio for Xiaohongshu posting. + +## Overview + +The skill performs the following workflow: + +1. **Accept Content**: Receives markdown, HTML, or txt format content from the user +2. **Load Prompt Template**: Reads the prompt template from `prompts/default.md` in this skill's directory +3. **Generate Cover Image**: Uses Gemini API to generate a cover image based on the article content +4. **Generate HTML**: Creates a beautifully styled HTML page following the prompt template specifications +5. **Save Output**: Saves the HTML to `/output//index.html` +6. **Capture Screenshots**: Takes sequential 3:4 ratio screenshots of the entire page without cutting text + +## Usage + +When the user invokes this skill, follow these steps: + +### Step 1: Identify the Input + +The user will provide one of the following: +- A file path to a markdown, HTML, or txt file (e.g., `/path/to/article.md`) +- Raw content directly in the conversation +- A URL to fetch content from + +If the input is unclear, ask the user to provide either a file path, URL, or paste the content directly. + +### Step 2: Read the Prompt Template + +Read the prompt template from this skill's directory: + +``` +{{SKILL_DIR}}/prompts/default.md +``` + +Use the Read tool to get the prompt template content. This template defines the HTML/CSS styling specifications. + +### Step 3: Extract Article Title and Date + +From the content, extract: +- **Title**: The main heading (h1) or first significant title in the content +- **Date**: Current date in YYYY-MM-DD format + +Create the output folder name as: `-` +- Replace spaces with hyphens +- Remove special characters +- Keep it reasonably short (max 50 characters) + +### Step 4: Generate Cover Image with Gemini + +If the prompt template specifies image generation requirements (which it does by default): + +1. **Read the environment variables** from `{{SKILL_DIR}}/.env` to get `GEMINI_API_KEY` +2. **Analyze the article content** to extract the main theme +3. **Generate image prompt** based on the template: + - Style: Hand-drawn illustration similar to *The New Yorker* editorial cartoons + - Content: Visual representation of the article's main theme + - Dimensions: 600px × 350px (will be scaled to fit) + +4. **Call Gemini API** using the generate_images.py script: + +```bash +cd {{SKILL_DIR}} && python scripts/generate_images.py output//prompts.json +``` + +Or use direct API call via curl: + +```bash +curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash-exp:generateContent?key=${GEMINI_API_KEY}" \ + -H "Content-Type: application/json" \ + -d '{ + "contents": [{ + "parts": [{"text": ""}] + }], + "generationConfig": { + "responseModalities": ["TEXT", "IMAGE"] + } + }' +``` + +5. **Save the generated image** to `output//images/cover.png` + +### Step 5: Generate HTML + +Using the prompt template and the user's content: + +1. **Parse the content** to identify: + - Title (h1) + - Subtitles (h2-h6) + - Paragraphs + - Lists + - Code blocks + - Links + - Emphasis/bold text + - Blockquotes + +2. **Generate complete HTML** following the template specifications: + - Dark gradient background + - 600px × 800px cream-colored card + - Proper typography with Google Fonts (Noto Serif SC, Inter, JetBrains Mono) + - Cover image at the top + - All specified styling for text, links, lists, code blocks, etc. + - Responsive design for mobile + +3. **Important HTML Structure**: + +```html + + + + + + Article Title + + + + + +
+ Cover +
+ +
+
+ + +``` + +4. **Save the HTML** to `output//index.html` + +### Step 6: Take Screenshots + +After generating the HTML, capture sequential screenshots at 3:4 ratio (e.g., 1080×1440 pixels): + +1. **Open the HTML page** using Playwright browser +2. **Calculate screenshot sections**: + - Screenshot height: 1440px (at 1080px width for 3:4 ratio) + - Total page height / screenshot height = number of screenshots needed +3. **For each screenshot**: + - Ensure no text is cut off at boundaries + - If text would be cut, move the boundary to before that line and leave whitespace + - Use smart text detection to find safe cutting points +4. **Save screenshots** to `output//screenshots/`: + - `01.png`, `02.png`, `03.png`, etc. + +Use the screenshot script: + +```bash +cd {{SKILL_DIR}} && python scripts/screenshot.py output//index.html +``` + +### Step 7: Report Results + +After completion, report to the user: +- HTML file location +- Number of screenshots generated +- Screenshots folder location +- Preview of the first screenshot (if possible) + +## Directory Structure + +``` +{{SKILL_DIR}}/ +├── SKILL.md # This file +├── prompts/ +│ └── default.md # Default HTML/CSS styling prompt +├── scripts/ +│ ├── generate_images.py # Gemini image generation script +│ └── screenshot.py # Screenshot capture script +├── output/ # Generated outputs (gitignored) +│ └── / +│ ├── index.html +│ ├── images/ +│ │ └── cover.png +│ └── screenshots/ +│ ├── 01.png +│ ├── 02.png +│ └── ... +├── .env # Environment variables (gitignored) +├── .env.example # Environment variable template +└── .gitignore +``` + +## Environment Variables + +Required environment variables in `.env`: + +``` +GEMINI_API_KEY=your_gemini_api_key_here +``` + +Get your API key from: https://aistudio.google.com/app/apikey + +## Example Workflow + +**User:** Create a styled article page from this markdown: + +```markdown +# My Article Title + +This is the introduction paragraph... + +## Section 1 + +Content for section 1... +``` + +**Assistant Actions:** +1. Read prompt template from `prompts/default.md` +2. Extract title: "My Article Title" +3. Create output folder: `output/2024-01-14-my-article-title/` +4. Generate cover image using Gemini API based on article theme +5. Generate styled HTML following template specifications +6. Save to `output/2024-01-14-my-article-title/index.html` +7. Open in browser and take 3:4 ratio screenshots +8. Save screenshots to `output/2024-01-14-my-article-title/screenshots/` +9. Report completion with file locations + +## Custom Prompt Templates + +Users can provide custom prompt templates by: +1. Placing a `.md` file in the `prompts/` directory +2. Specifying the template name when invoking the skill + +Example: "Use the `xiaohongshu-style` template for this article" + +## Error Handling + +If the Gemini API call fails: +1. Display the error message to the user +2. Offer to retry or proceed without cover image +3. If proceeding without image, use a placeholder or omit the cover + +If screenshot capture fails: +1. Verify the HTML file exists and is valid +2. Check browser dependencies +3. Report the specific error to the user + +## Dependencies + +This skill requires: +- Python 3.8+ +- `python-dotenv` package +- Playwright for screenshot capture (installed via pip: `pip install playwright && playwright install chromium`) + +Install dependencies: + +```bash +pip install python-dotenv playwright +playwright install chromium +``` + +## Notes + +- The skill preserves all original content exactly as provided +- No modifications, simplifications, or deletions to the content +- The cover image is generated based on the article's main theme +- Screenshots are optimized for Xiaohongshu's 3:4 aspect ratio +- Text is never cut off in screenshots - boundaries are adjusted intelligently diff --git a/prompts/default.md b/prompts/default.md new file mode 100644 index 0000000..f7cfbe3 --- /dev/null +++ b/prompts/default.md @@ -0,0 +1,241 @@ +# HTML/CSS Article Image Expert Prompt + +You are a frontend development and web layout expert proficient in HTML/CSS. + +## Task Objective + +Please carefully read the article link or article content provided by the user, and generate a complete HTML page according to the following style specifications. The page should be presented as a cream-colored card on a dark background, with a modern feel and good reading experience. + +--- + +## 1. Overall Layout + +### 1.1 Page Background + +- **Dark gradient background** + +```css +background: linear-gradient(135deg, #1e1e2e 0%, #2d2b55 50%, #3e3a5f 100%); +background-attachment: fixed; +``` + +- **Layout method**: Use Flexbox to achieve vertical and horizontal centering + +### 1.2 Main Container (Cream-colored Card) + +- **Dimensions**: 600px × 800px +- **Background color**: `#F9F9F6` +- **border-radius**: 0px (card has no rounded corners, rectangular with right angles) +- **3D shadow** (three layers): + +```css +box-shadow: + 0 25px 50px rgba(0, 0, 0, 0.4), + 0 10px 30px rgba(0, 10, 20, 0.3), + 0 5px 15px rgba(0, 5, 15, 0.25); +``` + +### 1.3 Content Area + +- **Content area scope**: Cover image, title, and body text. Note: Cover is part of the content area and scrolls with the content; NEVER use `position: fixed` or `position: sticky` to make the cover image hover. +- **Padding**: `20px 50px 50px 50px` (top, right, bottom, left - top padding reduced to 20px) +- **Scrolling**: Vertical scrolling enabled +- **Custom scrollbar**: Fully transparent scrollbar or no scrollbar display + +- **CSS Implementation Key Points**: + - `.container` set `overflow-y: auto` + - `.content` only sets `padding`, no scrolling + - Cover image as direct child element of `.container`, positioned before `.content` + +--- + +## 2. Font System + +### 2.1 Import Fonts + +Import the following fonts from Google Fonts: + +- **Noto Serif SC** (Source Han Serif): `weight: 700` +- **Inter**: `weight: 300, 400, 700, 800` +- **JetBrains Mono**: `weight: 400, 700` + +### 2.2 Font Application Rules + +| Content Type | Font | +|--------------|------| +| Body default | System font stack (`-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto`, etc.) | +| H1 Main title | Noto Serif SC (Source Han Serif) | +| H2 Subtitle | Times New Roman | +| English titles | Inter | +| Code | JetBrains Mono | + +--- + +## 3. Text Style Specifications + +### 3.1 Cover Image + +- **Dimensions**: 600px × 350px +- **Image uses: object-fit: cover to ensure no compression** +- Generate a hand-drawn illustration/comic based on the content's main theme, in a style similar to *The New Yorker* editorial cartoons. (The comic reflects the article's meaning) + +### 3.2 Title Hierarchy + +| Element | Font | Size | Color | Weight | Line Height | Margin | +|---------|------|------|-------|--------|-------------|--------| +| `h1` | Noto Serif SC | 42px | `#000000` | 700 | 1.3 | `margin-bottom: 30px` | +| `h2` | Times New Roman | 26px | `#000000` | 700 | - | `margin: 40px 0 20px` | +| `h3` | Default | 22px | `#2c3e50` | 600 | - | `margin: 30px 0 15px` | +| `h4` | Default | 20px | `#5a6c7d` | 600 | - | `margin: 25px 0 12px` | + +### 3.3 Body Text + +- **Font size**: `20px` +- **Color**: `#333333` +- **Line height**: `2` +- **Paragraph spacing**: `margin-bottom: 20px` + +### 3.4 Special Text Classes + +**English title** (`.en-title`) + +- Font: Inter +- Size: 18px +- Color: `#888888` +- Weight: 300 + +**Metadata** (`.metadata`) + +- Size: 14px +- Color: `#888888` + +--- + +## 4. Emphasis and Markers + +### 4.1 Links (``) + +- Color: `#4a9eff` (blue) +- Default no underline +- Show underline on hover +- Transition effect: `transition: 0.2s ease` + +### 4.2 Emphasis (``) + +- Color: `#000000` (black) +- Font style: `normal` (not italic) +- **Usage**: Text that needs emphasis but not highlighting + +### 4.3 Bold (``) + +- **Usage**: Important keywords + +### 4.4 Highlight marker (``) + +- Background color: `#fff59d` (light yellow) +- Text color: `#000000` +- Weight: `bold` +- Bottom border: `2px solid #ff9800` (orange) +- Border radius: `4px` +- Padding: `2px 6px` + +--- + +## 5. Lists and Quotes + +### 5.1 Lists (`
    `, `
      `) + +- Font size: `20px` +- Left padding: `20px` +- Bottom margin: `margin-bottom: 20px` + +### 5.2 List items (`
    1. `) + +- Item spacing: `margin-bottom: 8px` + +### 5.3 Blockquote (`
      `) + +- Left border: `4px solid #4a9eff` (blue vertical line) +- Left padding: `20px` +- Font style: italic +- Top/bottom margin: `margin: 20px 0` + +--- + +## 6. Code Styles + +### 6.1 Code block (`
      `)
+
+- Font: JetBrains Mono
+- Size: `17px`
+- Background color: `#f5f5f5`
+- Border: `1px solid #e0e0e0`
+- Border radius: `6px`
+- Padding: `20px`
+- Line height: `1.6`
+- Horizontal scrolling enabled
+
+### 6.2 Inline code (``)
+
+- Font: JetBrains Mono
+- Size: inherit, slightly smaller
+- Background color: `#f5f5f5`
+- Padding: `2px 6px`
+- Border radius: `4px`
+
+---
+
+## 7. Responsive Design
+
+**Breakpoint**: `650px` and below
+
+| Element | Desktop | Mobile |
+|---------|---------|--------|
+| Body padding | `20px` | `10px` |
+| Body font size | `20px` | `20px` |
+| Container width | `600px` | `100%` |
+| Container height | `800px` | `auto` (min `80vh`) |
+| Content area padding | `50px` | `30px` |
+| H1 font size | `42px` | `36px` |
+| H2 font size | `26px` | `24px` |
+| List font size | `20px` | `20px` |
+| Code block font size | `17px` | `15px` |
+| Code block padding | `20px` | `15px` |
+
+---
+
+## 8. Output Requirements
+
+1. **Generate complete HTML5 document** with ``, ``, ``, `` tags
+2. **All styles inline in `