juneyaooo/xhs-writer
>- 生成小红书(RedNote)笔记：把主题或用户提供的素材(文字/图片/视频)做成一套竖版卡片(图文) 或一段带分镜脚本的视频稿(视频)，配 caption + hashtags，落盘到 output/小红书/。 使用时机：用户说 写小红书 / 做小红书笔记 / 小红书图文 / 小红书种草 / 出一套 xhs 卡片 / 小红书视频 / write a Xiaohongshu note / make a RedNote post。
npx skills add https://github.com/JuneYaooo/xhs-writer-skill --skill xhs-writer把一个主题 + (可选)用户素材，生成图文卡片组或短视频脚本，按规范落盘到 output/小红书/。
小红书读者看的不是长文，是卡片组或短视频。长文原稿只是中间产物；caption 只是发布配文。
meta.json.shots 里，视频合成本 skill 不做。5大核心原则：
详细方法论：见 references/xiaohongshu-viral-methodology.md
按顺序执行。不要跳步。
收到请求后不要动手，先向用户确认以下要点，尽量一条消息问完：
触发条件：
执行：
输出：
## 卖点/亮点分析结果
| 点 | 稀缺性 | 实用性 | 可感知 | 得分 | 优先级 |
|---|---|---|---|---|---|
| 亮点A | 5 | 5 | 5 | 125 | 🥇 核心 |
| 亮点B | 2 | 3 | 3 | 18 | 🥉 辅助 |
**核心卖点/亮点**：亮点A（聚焦这个，其他作为辅助）
参考：references/xiaohongshu-viral-methodology.md 第2节
如果用户提供了素材路径，先跑脚本生成清单，再由 AI 用多模态能力填描述：
python3 scripts/analyze_material.py <path>... \
--out <work-dir>/reference/materials.json \
--frames-dir <work-dir>/reference/frames
脚本只做确定性预处理(分类、取分辨率/时长、抽帧)。AI 随后用视觉能力 打开 materials.json 里每条 image/frame，填 caption 和 usage(cover / content-N / ending / reference)。详见 references/material-intake.md。
素材分类（按价值排序）：
素材使用策略：
参考：references/xiaohongshu-viral-methodology.md 第3节
按 references/reference-search.md 执行，结果写入同一 reference/ 目录。核心数据 ≥2 个来源交叉验证。
从 H2 开始(不写 H1；标题入 meta.json.title)。写完先给用户看，确认主旨再继续，不要直接跳到卡片/分镜。反模式清单以 references/humanizer-zh.md 为准。
读 references/humanizer-zh.md 五层原则，完整扫描重写原稿，给出质量评分(满分 50)。
触发条件：Step 1 发现了对比图、功能演示等高价值素材
工具：gpt-image-2 图生图（需要 OpenAI API key）
执行：
# 使用本项目的 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 模板：见 references/xiaohongshu-viral-methodology.md 附录C
失败处理：
scripts/text_on_image.py）cover(第 1 张) + content(中间若干) + ending(最后 1 张)title + content 合计，代码点计数)每张卡选一种 合成策略(写入 cardsi].synthesis_strategy)，五选一。详见 [references/material-intake.md：
| strategy | 适用 | 工具 | 优先级 |
|---|---|---|---|
| img2img | 有真实素材（对比图/演示图） | gpt-image-2 图生图 | 🥇 最佳 |
| text_on_photo | 有 1 张合适照片 + 一句钩子 | scripts/text_on_image.py | 🥈 次选 |
| collage | 有 2-4 张互补照片 | scripts/collage_3x4.py | 🥉 可用 |
| pure_text | 无素材，纯文字卡 | AI 生图（素人感） | ✅ 常用 |
| ai_generated | 概念图 / 数据图 | 用户自备 t2i 服务 | ⚠️ 慎用 |
策略选择原则：
img2img（保留真实感）pure_text（素人感设计）ai_generated（广告感强）素材有水印 → 先跑 scripts/crop_watermark.py 或按 references/image-sourcing.md 处理。
narration(口播，≤30 字)、on_screen_text(屏幕字，≤15 字)、visual(画面描述)、material_ref(若引用 materials.json 里某条素材)cover 卡(3:4)作为封面；视频本体由用户侧工具合成，本 skill 只产脚本字段结构见 references/meta-schema.md 的 shots[] 定义。
标题生成（5种公式）：
{具体痛点}？{解决方案}有没有那种{功能描述}的{产品类型}？我发现了个宝藏！{核心价值}{热点词}爆火后，我用它做了{场景}{身份标签}必备！{核心功能}参考：references/xiaohongshu-viral-methodology.md 附录F
caption：
hashtags：
#生活 等过度泛化标签只写进 meta.json，不粘进卡片或正文
目录与命名规则见 references/output-spec.md。
output/小红书/{YYYY-MM-DD}/{短标题}_{YYYYMMDDHHmm}/
├── {完整标题}.md # 长文原稿
├── meta.json # 元数据(卡片 / 分镜 / caption / hashtags / materials)
├── images/ # (图文)最终卡图 / (视频)封面
└── reference/ # materials.json / 搜索结果 / summary / 思考过程
目录短标题与时间戳必须走脚本标准化，别手写：
python3 scripts/normalize_slug.py "原始长标题" --with-ts
meta.json 完整字段定义见 references/meta-schema.md。
写完 meta.json 后必须跑：
python3 scripts/validate_meta.py <work-dir>/meta.json
非 0 退出 → 读报错修 meta.json 再跑，直到 clean。不要把未校验的产物交给用户。
meta.json.titlereference/.md 里留 【插入图片：...】 占位符；图片同步下载 + 引用相对路径normalize_slug.py~/.claude/skills/xhs-writer-skill/.env 填入 OPENAI_API_KEY# 添加路径
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' # 图生图模式
)
references/xiaohongshu-viral-methodology.md：完整爆款方法论references/humanizer-zh.md：去 AI 化原则references/material-intake.md：素材处理流程references/image-sourcing.md：图片来源处理references/meta-schema.md：元数据字段定义references/output-spec.md：输出目录规范# 用户说："帮我推广这个项目 /path/to/project"
# Step 0.5: 卖点分析
# → 列出功能，让用户打分（稀缺性×实用性×可感知）
# → 选出核心卖点
# Step 1: 素材盘点
# → 扫描项目截图、对比图、演示图
# → 分类：对比图（最有价值）> 功能演示 > 其他
# Step 4.5: 图生图
# → 对比图用图生图（保留真实感 + 小红书风格）
# → 纯文字卡片用 AI 生图（素人感）
# Step 6: 生成标题（5个选项）
# → 痛点式、提问式、发现式、热点词、身份共鸣
# 输出：6-7张卡片 + caption + hashtags
# 用户说："写一条关于 XX 好物推荐的小红书笔记"
# Step 0: Intake
# → 确认主题、目标读者、输出形态
# Step 0.5: 亮点分析
# → 这个好物的核心亮点是什么？
# Step 1: 素材盘点
# → 产品图、使用场景图、效果对比图
# Step 3-4: 写长文 + 去 AI 化
# Step 5: 拆成卡片
# → 封面（提问/发现式）+ 亮点展示 + 使用场景 + 真实体验 + CTA
# 输出：5-7张卡片 + caption + hashtags
# 用户说："写一条关于 XX 知识的小红书笔记"
# Step 0: Intake
# → 确认主题、目标读者、知识点
# Step 2: 采集外部参考
# → 搜索相关资料，交叉验证
# Step 3-4: 写长文 + 去 AI 化
# Step 5: 拆成卡片（纯文字）
# → 用 AI 生图（素人感设计）
# → 结构：封面 + 核心概念 + 步骤/要点 + 注意事项 + CTA
# Step 6: caption + hashtags
# 输出：5-7张卡片 + caption + hashtags
A：有真实素材（对比图、演示图、截图）时优先用图生图。效果：真实感 > 代码叠加 > 纯 AI 生图。
A：用公式 优先级 = 稀缺性(1-5) × 实用性(1-5) × 可感知(1-5)，选择得分最高的 1-2 个作为核心卖点。
A：
A：三级降级策略
scripts/text_on_image.py）A：
更新时间：2026-04-25
适用场景：产品推广、好物分享、知识科普、经验总结、测评对比等各类小红书内容
Take juneyaooo/xhs-writer from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.