XHS Image Generator Skill

Generate professional Xiaohongshu carousel images from structured content JSON. Outputs 3:4 vertical PNGs (1080x1440) with Chinese typography, ready for upload.

---

Setup

Clone the skill:

git clone https://github.com/PHY041/claude-agent-skills
cd claude-agent-skills/skills/xhs-image-gen
python3 -m venv venv
venv/bin/pip install -r requirements.txt

Optional — AI cover generation (uses fal.ai):

export FAL_API_KEY="your_fal_api_key"

---

Quick Start

# Template-only (fast, free)
venv/bin/python3 generate.py content.json --output /tmp/xhs-output/

# AI cover + template content (recommended)
FAL_API_KEY="..." venv/bin/python3 generate.py content.json --ai-cover --output /tmp/xhs-output/

---

Workflow

Step 1: Understand the Topic

When user asks to create XHS content for topic X:

1. Understand the topic and target audience
2. Plan 4-6 slides (cover + 2-4 content + summary)
3. Choose appropriate template

Step 2: Decide on Cover Style

Mode	Flag	When to Use
Gradient cover (default)	(none)	Clean, fast, no API cost
AI cover	--ai-cover	Eye-catching background via fal.ai

AI cover uses flux/schnell to generate an atmospheric background, applies a dark gradient overlay, and renders white text on top. Content slides always use templates (no AI). Cost: ~$0.003 per cover.

Step 3: Generate Content JSON

{
  "template": "tutorial",
  "ai_cover": true,
  "slides": [
    {
      "type": "cover",
      "title": "大标题（简短有力）",
      "subtitle": "副标题（补充说明）",
      "tag": "分类标签",
      "author": "@your_handle",
      "ai_prompt": "optional: custom fal.ai prompt for background"
    },
    {
      "type": "content",
      "title": "第一个要点",
      "number": 1,
      "body": "详细说明\n用换行分段\n每段1-2句话",
      "highlight": "可选：重点提示框内容"
    },
    {
      "type": "list",
      "title": "清单/工具列表",
      "items": [
        "第一项 — 简短说明",
        "第二项 — 简短说明",
        "第三项 — 简短说明"
      ]
    },
    {
      "type": "summary",
      "title": "总结",
      "points": [
        "核心收获一",
        "核心收获二",
        "核心收获三"
      ],
      "cta": "关注我获取更多干货"
    }
  ]
}

Step 4: Generate Images

cat > /tmp/xhs-content.json << 'EOF'
{... your JSON here ...}
EOF

venv/bin/python3 generate.py /tmp/xhs-content.json --output /tmp/xhs-output/

Step 5: Present to User

Show the generated images for review. If approved, they're ready for manual upload to Xiaohongshu.

---

Available Templates

Template	Style	Best For
tutorial	White bg, blue accent	How-to, tutorials, step-by-step
dark	Dark bg, soft blue accent	Tech, dev tools, coding
warm	Cream bg, amber accent	Lifestyle, personal stories
nature	Light green bg, green accent	Wellness, growth, nature
coral	Light pink bg, red accent	Alerts, hot takes, comparisons

Select with --template dark or set "template": "dark" in JSON.

Custom Accent Color

Override with "accent_color": "#FF6B6B" in the JSON root.

---

Content Rules (CRITICAL)

Slide Count

• Minimum 3 slides (cover + 1 content + summary)
• Optimal 4-6 slides (XHS algorithm favors multi-image carousels)
• Maximum 9 slides (beyond this, completion rate drops)

Text Length Per Slide

• Title: 6-12 characters (Chinese) — must be scannable
• Body: 4-6 lines max per slide — don't cram
• List items: 8 max per slide
• CTA: Under 12 characters

Language & Tone

• Write in Chinese (simplified)
• 朋友分享 tone — like telling a friend, not marketing
• Short sentences, line breaks between ideas
• Concrete numbers > vague claims ("省90%时间" > "节省大量时间")

What NOT to Do

• No English-only slides (mixed OK, pure English bad for XHS)
• No walls of text (if body > 6 lines, split into 2 slides)
• No generic AI-sounding language
• No hype words: 颠覆、革命性、10倍、全网最强

---

CLI Options

generate.py <content.json> [--template NAME] [--output DIR] [--ai-cover]
generate.py --list-templates

Flag	Effect
--ai-cover	Generate fal.ai background for cover slide
--template	Template preset (tutorial, dark, warm, nature, coral)
--output	Output directory (default: ./output)

AI cover also activatable via JSON: set "ai_cover": true in the root object.

Output

• Files named slide-01-cover.png, slide-02-content.png, etc.
• All 1080x1440px (3:4 vertical)
• PNG format, ready for XHS upload

---

Example

Test with the bundled example:

venv/bin/python3 generate.py example.json --output /tmp/xhs-test/
open /tmp/xhs-test/  # Preview on macOS