pw-image-generation

Image-Generation - AI image generation workflow

Core Concept: Analyze style → Design prompts → User confirmation → Generate images, avoiding quota waste

Core Features

Image Generation:

Text-to-image: Generate images based on text descriptions
Image-to-image: Generate images in a similar style based on reference images
Batch generation: Use prompt templates to generate multiple images in batches
Style consistency: Keep the visual style of a series of images unified

Image Processing:

Long image merging: Vertically stitch a series of images into one long image
PPT packaging: Package a series of images into a PPT file (one image per page)
Image hosting management: Upload images to an image host and manage deletion links

When to Use

Applicable Scenarios:

The user explicitly requests "generate an image", "create an illustration", or "make an illustration"
The user provides a text description and needs a visual representation
The user provides a reference image and requests generation of an image in a similar style
The user needs illustrations for an article, PPT, or social media
The user needs to batch-generate a series of images with a consistent style
The user needs to merge multiple images into a long image or PPT

Not Applicable Scenarios:

The user is only asking how to generate images (providing suggestions is sufficient)
The user needs to edit existing images (use an image editing tool)
The user needs image recognition or analysis (use a visual analysis tool)
The user needs screenshots or screen recording (use a system tool)

Workflow

分析风格 → 设计提示词 → 安装依赖 → 配置API → 确认生成 → 保存图像
    ↓          ↓           ↓         ↓         ↓         ↓
  风格文件    提示词文件   node-fetch  secrets.md  逐张确认  images/

Script Directory

All scripts are located in the ~/.claude/skills/pw-image-generation/scripts/ directory.

Agent Execution Instructions:

Determine the directory path of this SKILL.md file as SKILL_DIR
Script path = ${SKILL_DIR}/scripts/<script-name>.ts
Replace all ${SKILL_DIR} in this document with the actual path

Available Scripts:

Script	Function	Parameters
`generate-image.ts`	Generate images (confirm one by one)	`[输出目录]`
`upload-image.ts`	Upload images to image host	`<图片路径>`
`delete-image.ts`	Manage image host images	`list\|delete <索引>\|delete-all`
`merge-to-long-image.ts`	Merge into long image	`<图片目录> <输出文件>`
`merge-to-pptx.ts`	Package as PPT	`<图片目录> <输出文件>`
`analyze-image.ts`	Analyze image style	`<图像URL或路径>`

Quick Start

Step 1: Create project directory

mkdir my-image-project && cd my-image-project

Step 2: Copy configuration template (optional)

cp -r ~/.claude/skills/pw-image-generation/config.example ./config
cp ~/.claude/skills/pw-image-generation/references/.gitignore.template ./.gitignore
# 编辑 config/secrets.md 自定义 API 密钥（可选）

Step 3: Create prompts

mkdir -p prompts
cp ~/.claude/skills/pw-image-generation/references/prompt-templates/提示词模板.md ./prompts/我的提示词.md
vim ./prompts/我的提示词.md

Refer to references/style-library.md to choose an appropriate style.

Step 4: Generate images

npx -y bun ~/.claude/skills/pw-image-generation/scripts/generate-image.ts

The script will ask for confirmation one by one to avoid wasting quota.

Tool Script Details

1. Generate Images

Command:

npx -y bun ~/.claude/skills/pw-image-generation/scripts/generate-image.ts [输出目录]

Parameter Description:

[输出目录]: Optional, specify the image save directory, default is ./images

Workflow:

Read all prompt files under the prompts/ directory
Display prompt contents one by one
Ask whether to generate that image (y/n/q)
Generate images and save them to the output directory
Supports interruption and recovery

Confirm option:

y (yes): Generate the current image
n (no): Skip the current image and continue to the next one
q (quit): Exit the generation process

Example:

# 使用默认输出目录
npx -y bun ~/.claude/skills/pw-image-generation/scripts/generate-image.ts

# 指定输出目录
npx -y bun ~/.claude/skills/pw-image-generation/scripts/generate-image.ts ./my-images

2. Upload an image to the image hosting service

Command:

npx -y bun ~/.claude/skills/pw-image-generation/scripts/upload-image.ts <图片路径>

Parameter description:

<图片路径>: Required, the path to the local image file to upload

Features:

Automatically uploads to freeimage.host (permanent storage)
Returns a usable image URL
Automatically saves the deletion link to .upload-history.json
Used for uploading reference images for image-to-image

Example:

# 上传单张图片
npx -y bun ~/.claude/skills/pw-image-generation/scripts/upload-image.ts ./template/参考图.png

# 上传后会返回:
# - 图片 URL (用于提示词中的 image_url)
# - 删除链接 (保存在历史记录中)

Output example:

上传成功!
图片 URL: https://iili.io/xxx.png
删除链接已保存到 .upload-history.json

3. Manage image hosting images

Command:

# 列出所有上传的图片
npx -y bun ~/.claude/skills/pw-image-generation/scripts/delete-image.ts list

# 删除指定索引的图片
npx -y bun ~/.claude/skills/pw-image-generation/scripts/delete-image.ts delete <索引>

# 删除所有图片
npx -y bun ~/.claude/skills/pw-image-generation/scripts/delete-image.ts delete-all

Parameter description:

list: List all upload records
delete <索引>: Delete the image at the specified index (index starts at 0)
delete-all: Delete all images

Features:

View upload history and deletion links
Delete images individually or in batches
Automatically update the history record file

Example:

# 查看上传历史
npx -y bun ~/.claude/skills/pw-image-generation/scripts/delete-image.ts list
# 输出:
# 0: 参考图.png - https://iili.io/xxx.png (2024-01-15)
# 1: 配图1.png - https://iili.io/yyy.png (2024-01-16)

# 删除索引为 0 的图片
npx -y bun ~/.claude/skills/pw-image-generation/scripts/delete-image.ts delete 0

# 删除所有图片 (会要求确认)
npx -y bun ~/.claude/skills/pw-image-generation/scripts/delete-image.ts delete-all

For detailed instructions, see references/图床上传.md

4. Merge into a long image

Command:

npx -y bun ~/.claude/skills/pw-image-generation/scripts/merge-to-long-image.ts <图片目录> <输出文件>

Parameter description:

<图片目录>: Required, the directory containing the images to merge
<输出文件>: Required, the output long image filename

Features:

Vertically stitch multiple images
Automatically recognizes jpg/png/gif/webp formats
Sorts by numeric filename
Keeps the original image width and automatically calculates the height

Dependency requirements: ImageMagick needs to be installed:

brew install imagemagick

Example:

# 合并 images 目录下的所有图片
npx -y bun ~/.claude/skills/pw-image-generation/scripts/merge-to-long-image.ts ./images 长图.png

# 指定其他目录
npx -y bun ~/.claude/skills/pw-image-generation/scripts/merge-to-long-image.ts ./my-images 合集.jpg

Use cases:

Create long images for Xiaohongshu/WeChat Official Accounts
Merge screenshots from a tutorial series
Create image collection displays

5. Merge into PPT

Command:

npx -y bun ~/.claude/skills/pw-image-generation/scripts/merge-to-pptx.ts <图片目录> <输出文件>

Parameter description:

<图片目录>: Required, the directory containing the images to package
<输出文件>: Required, the output PPT filename

Features:

Each image occupies one page
Automatically recognizes jpg/png/gif/webp formats
Sorts by numeric filename
16:9 aspect ratio, automatically adapts to page size
Displays images centered

Example:

# 打包 images 目录下的图片为 PPT
npx -y bun ~/.claude/skills/pw-image-generation/scripts/merge-to-pptx.ts ./images 配图.pptx

# 指定其他目录
npx -y bun ~/.claude/skills/pw-image-generation/scripts/merge-to-pptx.ts ./my-images 展示.pptx

Use cases:

Quickly create image demonstration PPTs
Package a series of accompanying images for sharing
Organize generated images into a presentation document

6. Analyze image style

Command:

# 从 URL 分析
npx -y bun ~/.claude/skills/pw-image-generation/scripts/analyze-image.ts <图像URL>

# 从本地文件分析
npx -y bun ~/.claude/skills/pw-image-generation/scripts/analyze-image.ts <本地路径>

Parameter description:

<图像URL或路径>: Required, the image URL or local file path to analyze

Features:

Analyze the visual style of an image
Generate suitable prompt suggestions
Identify colors, composition, and artistic style
Save the analysis results to the analysis/ directory

Example:

# 分析在线图片
npx -y bun ~/.claude/skills/pw-image-generation/scripts/analyze-image.ts https://example.com/image.jpg

# 分析本地图片
npx -y bun ~/.claude/skills/pw-image-generation/scripts/analyze-image.ts ./template/参考图.png

Use cases:

Learn the style characteristics of reference images
Prepare prompts for image-to-image
Understand how to describe specific visual styles

File structure

Project directory structure

my-image-project/
├── config/
│   └── secrets.md           # API 配置（可选）
├── template/                # PDF 模板图片
├── prompts/                 # 提示词文件
├── analysis/                # 风格分析（可选）
├── images/                  # 生成的图像
└── .gitignore

Skill directory structure

pw-image-generation/
├── SKILL.md                  # 本文件（核心文档）
├── config.example/           # 配置模板
│   ├── README.md             # 配置说明
│   └── secrets.md            # API 配置模板
├── references/               # 参考文档
│   ├── .gitignore.template   # Git 忽略文件模板
│   ├── 图床上传.md           # 图床上传指南
│   ├── style-library.md      # 风格库（9种预设风格）
│   └── prompt-templates/
│       └── 提示词模板.md     # 提示词模板
└── scripts/
    ├── analyze-image.ts      # 分析图像风格
    ├── generate-image.ts     # 生成图像（支持确认和跳过）
    ├── upload-image.ts       # 上传图片到图床
    ├── delete-image.ts       # 管理和删除图床图片
    ├── merge-to-long-image.ts       # 合并长图
    └── merge-to-pptx.ts        # 打包为 PPT

Common issues and error handling

1. Image generation failed

Issue: Image generation failed or returned an error

Possible Causes:

API key not configured or invalid
Incorrect prompt format
Network connection issue
Insufficient API quota

Solutions:

# 检查配置文件
cat config/secrets.md

# 验证提示词格式
cat prompts/提示词.md

# 测试网络连接
curl -I https://api.openai.com

# 查看详细错误信息 (脚本会自动显示)

2. Image Hosting Upload Failed

Issue: Failed to upload the image to the image hosting service

Possible Causes:

The image file does not exist or the path is incorrect
The image format is not supported
The image file is too large (over 10MB)
Network connection issue

Solutions:

# 检查文件是否存在
ls -lh ./template/图片.png

# 检查文件大小
du -h ./template/图片.png

# 如果文件过大，压缩图片
# 使用 ImageMagick 压缩
convert ./template/图片.png -quality 85 -resize 2000x2000\> ./template/图片_compressed.png

3. Merging Long Images Failed

Issue: Error "ImageMagick not found" when merging long images

Possible Causes:

ImageMagick is not installed
ImageMagick is not added to PATH

Solutions:

# macOS 安装
brew install imagemagick

# 验证安装
convert --version

# 如果仍然失败，检查 PATH
which convert

4. PPT Generation Failed

Issue: An error occurs when generating the PPT or the PPT cannot be opened

Possible Causes:

The image directory is empty or does not exist
The image format is not supported
The output file path is invalid

Solutions:

# 检查图片目录
ls -la ./images

# 检查图片格式 (支持 jpg/png/gif/webp)
file ./images/*.png

# 确保输出目录存在
mkdir -p ./output
npx -y bun ~/.claude/skills/pw-image-generation/scripts/merge-to-pptx.ts ./images ./output/配图.pptx

5. Prompts Not Taking Effect

Issue: The generated image does not match the prompt description

Possible Causes:

The prompt description is not specific enough
The prompt language is mixed (Chinese and English mixed)
The prompt is too long or too short
The style description is unclear

Solutions:

# 不好的提示词
一张图片

# 好的提示词
水彩风格，温馨的咖啡馆场景，柔和的光线，暖色调，手绘质感

# 使用风格库
参考 references/style-library.md 选择合适的风格描述

6. Batch Generation Interrupted

Issue: Unexpected interruption during batch generation

Possible Causes:

Unstable network
User manually interrupted (Ctrl+C)
API rate limiting

Solutions:

The script will automatically skip images that have already been generated
Re-run the generation command to continue
Already generated images will not be generated again
Use the n option to skip images you do not need

7. Configuration File Issues

Issue: The configuration file does not take effect or cannot be found

Possible Causes:

The configuration file path is incorrect
The configuration file format is incorrect
The configuration template was not copied

Solutions:

# 复制配置模板
cp -r ~/.claude/skills/pw-image-generation/config.example ./config

# 检查配置文件
cat config/secrets.md

# 配置文件格式示例
# API_BASE_URL=https://api.openai.com/v1
# API_KEY=sk-xxx

Best Practices

Image Size Specifications

Choose the appropriate image size according to different usage scenarios:

Scenario	Aspect Ratio	Recommended Pixels	Description
Article illustrations	16:9	1920×1080	HD standard, suitable for large-screen reading
WeChat Official Account cover	2.35:1	900×383	WeChat officially recommended size
Xiaohongshu cover/illustration	3:4	1242×1660	Xiaohongshu recommended, suitable for iPhone screens
X Article cover	5:2	1500×600	X Articles officially recommended
Paper illustrations	16:9	1920×1080	HD standard

Additional Notes:

Xiaohongshu also supports 1:1 (1080×1080) and 4:3 (1440×1080)
The secondary image cover of a WeChat Official Account can use 200×200 (1:1)

Usage Recommendations:

Specify size in the prompt: size: 1920x1080 or aspect_ratio: 16:9
Prefer recommended sizes to avoid composition imbalance caused by later cropping
Different platforms have different size requirements; confirm the target platform before generating

Prompt Design

Basic Principles:

Be specific and clear: describe the scene, style, colors, and composition in detail
Consistent style: use preset style descriptions from the style library
Consistent language: all English or all Chinese, avoid mixing
Moderate length: 50-200 characters is appropriate; too short lacks detail, too long easily becomes chaotic

Recommended Structure:

[风格] + [主体] + [场景] + [氛围] + [技术细节]

示例:
水彩风格，一只可爱的小猫，坐在窗台上，温暖的午后阳光，柔和的色彩，手绘质感

Reference Resources:

references/style-library.md: 9 preset styles
references/prompt-templates/提示词模板.md: prompt templates

Image Generation Workflow

Recommended Steps:

First generate 1-2 test images to verify the prompt's effect
Adjust the prompt based on the test results
After confirming satisfactory results, batch-generate the remaining images
Use the confirmation mechanism to avoid wasting API quota
Regularly back up generated images

Avoid Waste:

Carefully check the prompt before each generation
Use the n option to skip unwanted images
Use the q option to exit promptly
Do not blindly batch-generate

Image-to-Image Tips

Upload a reference image:

# 1. 上传参考图到图床
npx -y bun ~/.claude/skills/pw-image-generation/scripts/upload-image.ts ./template/参考图.png

# 2. 复制返回的 URL

# 3. 在提示词中使用
# image_url: https://iili.io/xxx.png
# prompt: 类似风格的场景，保持色调和构图

Notes:

Reference image size is recommended to be 1024x1024 or larger
Reference image clarity should be high
The prompt should clearly state which features to preserve
You can try different prompt combinations multiple times

File Management

Suggested Directory Structure:

my-image-project/
├── config/              # 配置文件 (不提交到 git)
├── template/            # 参考图片
├── prompts/             # 提示词文件
│   ├── 01-封面.md
│   ├── 02-内容1.md
│   └── 03-内容2.md
├── images/              # 生成的图像
│   ├── 01-封面.png
│   ├── 02-内容1.png
│   └── 03-内容2.png
└── output/              # 最终输出 (长图/PPT)

Naming Conventions:

Prompt files: use numeric prefixes for sorting (01-, 02-, 03-)
Generated images: automatically use the prompt file name
Facilitates batch processing and sorting

Performance Optimization

Improve Generation Speed:

Use smaller image sizes (1024x1024 instead of 2048x2048)
Avoid overly complex prompts
Use image-to-image reasonably (faster than text-to-image)

Save API Quota:

Use the confirmation mechanism; do not skip confirmation
Test a single image first, then batch-generate
Save good prompts as templates for reuse
Regularly clean up unneeded images on the image host

Quality Control

Checklist:

Prompt description is clear and specific
Style description is consistent and uniform
Test image results are satisfactory
Image size and format are correct
File naming is standardized and orderly
Back up important images

Common Issues:

Inconsistent image style: check the style description in the prompt
Poor image quality: add technical detail descriptions (such as "high definition", "rich in detail")
Image content deviation: make the prompt more specific and add constraints

Important Notes

Avoid Wasting Quota

Confirmation is requested before each generation
Supports skipping already generated images
Generate one at a time to avoid consuming quota in batches

Configuration Management

Config file config/secrets.md is optional
When not configured, default configuration is used (requires setting the API_KEY environment variable)
The config file is not committed to version control (already in .gitignore)
Supports custom API endpoints and models

Runtime environment

The script runs with Bun, no need to install dependencies locally:

# 直接运行，Bun 会自动处理依赖
npx -y bun ~/.claude/skills/pw-image-generation/scripts/generate-image.ts

System requirements:

Node.js or Bun runtime
macOS/Linux/Windows (WSL)
Merging long images requires ImageMagick

Configuration instructions

See config.example/secrets.md for configuration options:

Configurable items:

API_BASE_URL: API base URL (default: OpenAI API)
ANALYSIS_MODEL_ID: Image analysis model (default: gpt-4-vision-preview)
GENERATION_MODEL_ID: Image generation model (default: dall-e-3)
API_KEY: API key (required)

Configuration example:

# config/secrets.md
API_BASE_URL=https://api.openai.com/v1
ANALYSIS_MODEL_ID=gpt-4-vision-preview
GENERATION_MODEL_ID=dall-e-3
API_KEY=sk-your-api-key-here

Style library

Skill provides 9 preset styles to ensure image style consistency:

Watercolor style (watercolor) - soft and warm
Flat design (flat-design) - modern and concise
3D render (3d-render) - three-dimensional and realistic
Oil painting style (oil-painting) - artistic and classic
Cyberpunk (cyberpunk) - sci-fi future
Pixel art (pixel-art) - retro and nostalgic
Hand-drawn illustration (hand-drawn) - warm and personalized
Photorealistic (photorealistic) - highly realistic
Abstract art (abstract) - emotional expression

See references/style-library.md for detailed descriptions of each style and usage scenarios.

Usage suggestions

Agent usage guide

When the user requests image generation:

Confirm requirements: Ask the user about image purpose, style preference, quantity
Prepare environment: Guide the user to create the project directory and configuration
Design prompts: Design prompts based on requirements, refer to the style library
Generate tests: First generate 1-2 test images
Batch generation: Generate in batches after confirming the results
Post-processing: Merge long images or package PPT as needed

Typical workflow

Scenario 1: Article illustrations

# 1. 创建项目
mkdir article-images && cd article-images

# 2. 准备提示词
mkdir prompts
# 创建 prompts/01-封面.md, 02-配图1.md 等

# 3. 生成图像
npx -y bun ~/.claude/skills/pw-image-generation/scripts/generate-image.ts

# 4. 合并长图 (可选)
npx -y bun ~/.claude/skills/pw-image-generation/scripts/merge-to-long-image.ts ./images 长图.png

Scenario 2: PPT illustrations

# 1. 创建项目
mkdir ppt-images && cd ppt-images

# 2. 准备提示词 (按页面顺序命名)
mkdir prompts
# 创建 prompts/01-标题页.md, 02-内容1.md 等

# 3. 生成图像
npx -y bun ~/.claude/skills/pw-image-generation/scripts/generate-image.ts

# 4. 打包为 PPT
npx -y bun ~/.claude/skills/pw-image-generation/scripts/merge-to-pptx.ts ./images 配图.pptx

Scenario 3: Image-to-image

# 1. 上传参考图
npx -y bun ~/.claude/skills/pw-image-generation/scripts/upload-image.ts ./template/参考图.png

# 2. 在提示词中使用返回的 URL
# prompts/01-类似风格.md:
# image_url: https://iili.io/xxx.png
# prompt: 类似风格的场景，保持色调和构图

# 3. 生成图像
npx -y bun ~/.claude/skills/pw-image-generation/scripts/generate-image.ts

Command quick reference

# 生成图像
npx -y bun ~/.claude/skills/pw-image-generation/scripts/generate-image.ts [输出目录]

# 上传图片
npx -y bun ~/.claude/skills/pw-image-generation/scripts/upload-image.ts <图片路径>

# 管理图床
npx -y bun ~/.claude/skills/pw-image-generation/scripts/delete-image.ts list
npx -y bun ~/.claude/skills/pw-image-generation/scripts/delete-image.ts delete <索引>
npx -y bun ~/.claude/skills/pw-image-generation/scripts/delete-image.ts delete-all

# 合并长图
npx -y bun ~/.claude/skills/pw-image-generation/scripts/merge-to-long-image.ts <图片目录> <输出文件>

# 打包 PPT
npx -y bun ~/.claude/skills/pw-image-generation/scripts/merge-to-pptx.ts <图片目录> <输出文件>

# 分析图像
npx -y bun ~/.claude/skills/pw-image-generation/scripts/analyze-image.ts <图像URL或路径>

About this skill

Core Features

When to Use

Workflow

Script Directory

Quick Start

Step 1: Create project directory

Step 2: Copy configuration template (optional)

Step 3: Create prompts

Step 4: Generate images

Tool Script Details

1. Generate Images

2. Upload an image to the image hosting service

3. Manage image hosting images

4. Merge into a long image

5. Merge into PPT

6. Analyze image style

File structure

Project directory structure

Skill directory structure

Common issues and error handling

1. Image generation failed

2. Image Hosting Upload Failed

3. Merging Long Images Failed

4. PPT Generation Failed

5. Prompts Not Taking Effect

6. Batch Generation Interrupted

7. Configuration File Issues

Best Practices

Image Size Specifications

Prompt Design

Image Generation Workflow

Image-to-Image Tips

File Management

Performance Optimization

Quality Control

Important Notes

Avoid Wasting Quota

Configuration Management

Runtime environment

Configuration instructions

Style library

Usage suggestions

Agent usage guide

Typical workflow

Command quick reference