xhs-writer

xhs-writer — Xiaohongshu note generation

From a topic + (optional) user material, generateimage-text card setorshort video script, saved to spec to output/小红书/。

Core philosophy

Xiaohongshu readers don't read long articles, they readcard setsorshort videos. The long-form draft is only an intermediate product; the caption is only the publishing copy.

Image post: 3-9 9:16 vertical cards (cover + content × N + ending), each ≤80 Chinese characters.
Video post: a 15-90 second vertical video script + cover card, storyboard written in meta.json.shots , video compositing is not done by this skill.

Viral methodology (general principles)

5 core principles：

Real material first: project screenshots, comparison images, demo images > pure AI-generated images
Focus on core selling points: use a formula to judge priority (see Step 0.5)
Amateur feel design: solid background + large emoji + colloquial > brand promotion style
Pain point oriented: say "what problem it solves" > pile up feature lists
Rapid iteration: V1 (60 points) → user feedback → V2 (70 points) → continuous optimization

Detailed methodology: see references/xiaohongshu-viral-methodology.md

Workflow

Execute in order.Do not skip steps。

Step 0 — Intake (must ask, ask all at once)

After receiving the request, do not start; first confirm the following points with the user, and try to ask them all in one message:

Topic / target readers / core viewpoint
Output form: image-text or video? (default image-text)
Material: is there existing text/images/video to use? Paste paths or drag files
Style: minimalist fresh / tech feel / ins style / business / literary retro / cute cartoon (default "minimalist fresh")
Number of cards / video duration: image-text default 5-7 cards; video default 30-60 seconds

Step 0.5 — Selling point/highlight analysis (recommended)

Trigger conditions：

Promotion type: products, projects, tools, services
Sharing type: good product recommendations, experience summaries, knowledge popularization
Review type: product comparisons, usage experience

Execution：

List all functions/features/highlights
Use AskUserQuestion to let the user rate (each point):
- Scarcity (1-5): do others have it? Is it unique?
- Usefulness (1-5): how big a problem can it solve?
- Perceivability (1-5): can users directly see/feel it?
Calculate score = scarcity × usefulness × perceivability
Sort, choose Top 1-2 as core selling points/highlights

Output：

## 卖点/亮点分析结果

| 点 | 稀缺性 | 实用性 | 可感知 | 得分 | 优先级 |
|---|---|---|---|---|---|
| 亮点A | 5 | 5 | 5 | 125 | 🥇 核心 |
| 亮点B | 2 | 3 | 3 | 18 | 🥉 辅助 |

**核心卖点/亮点**：亮点A（聚焦这个，其他作为辅助）

Reference：references/xiaohongshu-viral-methodology.md Section 2

Step 1 — Asset inventory (only if assets exist)

If the user provides an asset path,first run the script to generate an inventory, then have the AI fill in descriptions using multimodal capabilities:

python3 scripts/analyze_material.py <path>... \
  --out <work-dir>/reference/materials.json \
  --frames-dir <work-dir>/reference/frames

The script only does deterministic preprocessing (classification, extracting resolution/duration, frame extraction). The AI then uses visual capabilities to open materials.json each image/frame in , fill in caption and usage(cover / content-N / ending / reference). See references/material-intake.md。

Asset classification (ordered by value)：

Comparison images(most valuable): before/after, input/output, comparisons of different versions
Feature demos: interface screenshots, operation flowcharts, effect displays
Data charts: performance comparisons, user growth, feature coverage
Brand assets: Logo, color scheme, official screenshots

Asset usage strategy：

✅ Priority: real assets > image-to-image > code overlay > pure AI-generated images
✅ Comparison images: use image-to-image (preserve realism + overlay Xiaohongshu-style text)
✅ Text-only cards: use AI-generated images (amateur-style design)
❌ Avoid: using pure AI-generated images for all cards (lacks realism)

Reference：references/xiaohongshu-viral-methodology.md Section 3

Step 2 — Collect external references (required for opinion / news types; can skip if purely asset-driven)

Follow references/reference-search.md to execute, writing results into the same reference/ directory. Core data must be cross-verified by ≥2 sources.

Step 3 — Write the long-form draft (2000-4000 words)

Start from H2 (do not write H1; the title goes into meta.json.title). When done,show the user first, confirm the main point before continuing, and do not jump directly to cards/storyboard. The anti-pattern list is based on references/humanizer-zh.md .

Step 4 — De-AI-ify

Read references/humanizer-zh.md the five-layer principles, fully scan and rewrite the draft, and give a quality score (out of 50).

Step 4.5 — Image-to-image processing (required when real assets exist)

Trigger condition: Step 1 found high-value assets such as comparison images and feature demos

Tool: gpt-image-2 image-to-image (requires OpenAI API key)

Execution：

# 使用本项目的 image_generator
import sys
sys.path.insert(0, '~/.claude/skills/xhs-writer-skill/scripts')
from image_generator import GptImage2Generator

generator = GptImage2Generator(aspect_ratio="9:16")

# 图生图：保留真实素材 + 叠加小红书风格文字
generator.generate_scene_image(
    scene_data={
        'index': 1,
        'image_prompt': """Based on the reference image, create a Xiaohongshu style card, 9:16 vertical.

Keep the original image visible.

Add overlays:
- Top: "{标题}"
- Bottom: "{引导文字}"

Style:
- Keep original clear
- Casual Xiaohongshu style
- Authentic feel"""
    },
    output_path='output.jpg',
    size='auto',
    reference_image_path='material.jpg'
)

Prompt template: see references/xiaohongshu-viral-methodology.md Appendix C

Failure handling：

Retry once
Lower the image resolution (max 1024px)
Switch to code-overlaid text (scripts/text_on_image.py）

Step 5 — Distribution: image-text or video

5A. Image-text post: split into 3-9 cards

Structure:cover(1st image) + content(several in the middle) + ending(last image)
Each card ≤80 characters (title + content total, counted by code points)
One card covers only one point; numbers / comparisons / punchy quotes get priority on cards
The whole set of cards keeps a consistent emoji style and color scheme

For each card choose one composition strategy(write into cards[i].synthesis_strategy), choose one of five. See references/material-intake.md：

strategy	Applicable	Tool	Priority
`img2img`	Has real material (comparison image/demo image)	gpt-image-2 image-to-image	🥇 Best
`text_on_photo`	Has 1 suitable photo + one hook line	`scripts/text_on_image.py`	🥈 Second choice
`collage`	Has 2-4 complementary photos	`scripts/collage_3x4.py`	🥉 Usable
`pure_text`	No material, pure text card	AI-generated image (ordinary-person feel)	✅ Commonly used
`ai_generated`	Concept image / data image	User-provided t2i service	⚠️ Use with caution

Strategy selection principles：

✅ Has real material → prioritize img2img(preserve authenticity)
✅ Pure text card → use pure_text(ordinary-person feel design)
❌ Avoid using ai_generatedfor all cards (strong advertising feel)

Material has watermark → first run scripts/crop_watermark.py or handle according to references/image-sourcing.md .

5B. Video post: write storyboard script

Write 6-12 storyboard shots, each 2-8 seconds, total duration aligned with user expectations
Each shot includes:narration(voiceover, ≤30 characters),on_screen_text(on-screen text, ≤15 characters),visual(visual description),material_ref(if referencing materials.json a certain material item)
Still need to produce one cover card (3:4) as the cover; the video itself is synthesized by user-side tools, this skill only produces the script

For field structure see references/meta-schema.md the shots[] definition.

Step 6 — caption + hashtags + title

Title generation (5 formulas)：

Pain point + solution：{具体痛点}？{解决方案}
- Applicable: tools/products with clear pain points
Question style：有没有那种{功能描述}的{产品类型}？
- Applicable: new tool recommendations, feature discovery
Discovery style：我发现了个宝藏！{核心价值}
- Applicable: excited sharing, good product recommendations
Trending words：{热点词}爆火后，我用它做了{场景}
- Applicable: riding trends, technical products
Identity resonance：{身份标签}必备！{核心功能}
- Applicable: products with a clear target audience

Reference：references/xiaohongshu-viral-methodology.md Appendix F

caption：

100-300 characters, start with a hook (number/question/exclamation) → key information → call to action (like/save/follow)
With emoji, bestie tone
Structure: pain point resonance → solution → specific features → real case → CTA
Avoid: piling up features, formal copy, advertising feel

hashtags：

5-8, strongly related to the topic
Core tags(4): trending words + core features + differentiated selling points + target audience
Auxiliary tags(4): scenario words + category words
Avoid #生活 and other overly generalized tags

Only write into meta.json，do notpaste into the card or body text

Step 7 — Save to disk

For directory and naming rules see references/output-spec.md。

output/小红书/{YYYY-MM-DD}/{短标题}_{YYYYMMDDHHmm}/
├── {完整标题}.md        # 长文原稿
├── meta.json            # 元数据(卡片 / 分镜 / caption / hashtags / materials)
├── images/              # (图文)最终卡图 / (视频)封面
└── reference/           # materials.json / 搜索结果 / summary / 思考过程

Directory short title and timestampMustgo through script standardization, do not handwrite:

python3 scripts/normalize_slug.py "原始长标题" --with-ts

meta.json For complete field definitions see references/meta-schema.md。

Step 8 — Validation (mandatory)

After writing meta.json must run:

python3 scripts/validate_meta.py <work-dir>/meta.json

Non-zero exit → read error and fix meta.json Run again until clean. Do not hand unvalidated output to the user.

Do not do

Do not write an H1; put only in the title meta.json.title
Do not write "References / 参考来源" at the end of the body; only put it in reference/
Do not leave .md in 【插入图片：...】 placeholders; download images locally + reference relative paths
Do not skip Step 4 (de-AI-ification) and Step 8 (validate)
Do not manually calculate directory names / timestamps yourself; always go through normalize_slug.py

Tool dependencies

Required tools

Python 3.8+
PIL (Pillow)

Optional tools

OpenAI API key (for image-to-image, recommended)
- Configuration: in ~/.claude/skills/xhs-writer-skill/.env fill in OPENAI_API_KEY
- It also works without an API key; it will generate text-only cards

Image-to-image usage

# 添加路径
import sys
sys.path.insert(0, '~/.claude/skills/xhs-writer-skill/scripts')
from image_generator import GptImage2Generator

# 初始化
generator = GptImage2Generator(aspect_ratio="9:16")

# 生成
generator.generate_scene_image(
    scene_data={'index': 1, 'image_prompt': '...'},
    output_path='output.jpg',
    size='auto',
    reference_image_path='material.jpg'  # 图生图模式
)

Reference materials

Core methodology

references/xiaohongshu-viral-methodology.md: Complete viral methodology
- Selling point priority judgment formula
- Material usage strategy (priority ranking)
- Viral card structure (standard 6-7 cards)
- Copywriting formula library (5 title formulas)
- Visual style guide (ordinary-person feel vs polished design)
- Image-to-image Prompt templates (3 scenarios)
- Common mistakes checklist (5 major mistakes + solutions)
- Tool usage guide

Other references

references/humanizer-zh.md: De-AI-ification principles
references/material-intake.md: Material processing workflow
references/image-sourcing.md: Image source handling
references/meta-schema.md: Metadata field definitions
references/output-spec.md: Output directory specification

Quick start

Scenario 1: Promote a product/project

# 用户说："帮我推广这个项目 /path/to/project"

# Step 0.5: 卖点分析
# → 列出功能，让用户打分（稀缺性×实用性×可感知）
# → 选出核心卖点

# Step 1: 素材盘点
# → 扫描项目截图、对比图、演示图
# → 分类：对比图（最有价值）> 功能演示 > 其他

# Step 4.5: 图生图
# → 对比图用图生图（保留真实感 + 小红书风格）
# → 纯文字卡片用 AI 生图（素人感）

# Step 6: 生成标题（5个选项）
# → 痛点式、提问式、发现式、热点词、身份共鸣

# 输出：6-7张卡片 + caption + hashtags

Scenario 2: Good finds sharing/experience summary

# 用户说："写一条关于 XX 好物推荐的小红书笔记"

# Step 0: Intake
# → 确认主题、目标读者、输出形态

# Step 0.5: 亮点分析
# → 这个好物的核心亮点是什么？

# Step 1: 素材盘点
# → 产品图、使用场景图、效果对比图

# Step 3-4: 写长文 + 去 AI 化

# Step 5: 拆成卡片
# → 封面（提问/发现式）+ 亮点展示 + 使用场景 + 真实体验 + CTA

# 输出：5-7张卡片 + caption + hashtags

Scenario 3: Knowledge popularization/tutorial

# 用户说："写一条关于 XX 知识的小红书笔记"

# Step 0: Intake
# → 确认主题、目标读者、知识点

# Step 2: 采集外部参考
# → 搜索相关资料，交叉验证

# Step 3-4: 写长文 + 去 AI 化

# Step 5: 拆成卡片（纯文字）
# → 用 AI 生图（素人感设计）
# → 结构：封面 + 核心概念 + 步骤/要点 + 注意事项 + CTA

# Step 6: caption + hashtags

# 输出：5-7张卡片 + caption + hashtags

FAQ

Q1: When should image-to-image be used?

A: When there are real materials (comparison images, demo images, screenshots), prioritize image-to-image. Effect: realism > code overlay > pure AI-generated images.

Q2: How do you determine selling point priority?

A: Use the formula 优先级 = 稀缺性(1-5) × 实用性(1-5) × 可感知(1-5), and choose the top 1-2 highest-scoring ones as the core selling points.

Q3: Which style should the cover use?

A：

Clear pain point → pain-point style
New tool recommendation → question style
Good finds sharing → discovery style
Riding a trend → trending-keyword style
Clear audience → identity-resonance style

Q4: What should be done if image-to-image fails?

A: Three-level fallback strategy

Retry once
Lower the image resolution (max 1024px)
Switch to code overlaying text (scripts/text_on_image.py）

Q5: How many cards are needed?

A：

Minimum: 3 cards (cover + core selling point + CTA)
Standard: 6 cards (cover + selling point + feature + audience + case + CTA)
Complete: 7 cards (+ open-source address/official link)

Update time：2026-04-25 Applicable scenarios: Various types of Xiaohongshu content such as product promotion, good finds sharing, knowledge popularization, experience summaries, review comparisons, etc.