phy041/xhs-image-gen

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