mage-cover-gen

name	mage-cover-gen
description	Generates article cover images with 6 design dimensions, 9 color palettes, 6 rendering styles, optional references, and flexible aspect ratios. Use when users ask to generate a cover image, article cover, hero image, visual header, or cover artwork.

Cover Image Generator

Generate elegant cover images for articles with 6-dimensional customization, and stitch multiple generated covers into large collage boards when users want a style overview or showcase image.

Usage

# Auto-select dimensions based on content
/mage-cover-gen path/to/article.md

# Quick mode: skip confirmation
/mage-cover-gen article.md --quick

# Specify dimensions
/mage-cover-gen article.md --type conceptual --palette warm --rendering flat-vector

# Style presets (shorthand for palette + rendering)
/mage-cover-gen article.md --style blueprint

# With reference images
/mage-cover-gen article.md --ref style-ref.png

# Stitch generated covers into a large board
/mage-cover-gen --collage covers/ --collage-style showcase-dark

# Direct content input
/mage-cover-gen --palette mono --aspect 1:1 --quick
[paste content]

Reference Loading Guide

Keep SKILL.md lean and load references only when the current step needs them:

• Read references/config/preferences-schema.md only when creating, validating, or editing EXTEND.md.
• Read references/config/first-time-setup.md only when no preference file exists and setup must run.
• Read references/workflow/confirm-options.md only when dimensions need confirmation.
• Read references/workflow/prompt-template.md and references/workflow/reference-images.md only when building prompts/cover.md or processing references.
• Read references/workflow/collage-workflow.md only when the user wants a stitched collage / board / large combined image.
• Read references/collage-styles.md only when choosing a collage presentation style.
• Read palette, rendering, type, and dimension reference files only for the options that were selected or need comparison.
• Read references/compatibility.md only when checking whether a palette / rendering / type / text / mood / font combination is a strong fit.

Options

Option	Description
--type <name>	hero, conceptual, typography, metaphor, scene, minimal
--palette <name>	warm, elegant, cool, dark, earth, vivid, pastel, mono, retro
--rendering <name>	flat-vector, hand-drawn, painterly, digital, pixel, chalk
--style <name>	Preset shorthand (see Style Presets)
--text <level>	none, title-only, title-subtitle, text-rich
--mood <level>	subtle, balanced, bold
--font <name>	clean, handwritten, serif, display
--aspect <ratio>	16:9 (default), 2.35:1, 4:3, 1:1, 3:4
--lang <code>	Title language (en, zh, ja, etc.)
--no-title	Alias for --text none
--quick	Skip confirmation, use auto-selection
--ref <files...>	Reference images for style/composition guidance
--collage <dir-or-files>	Stitch existing generated images into a large board
--collage-style <name>	grid-dark, grid-light, showcase-dark, showcase-light

Six Design Dimensions

Dimension	Values	Default
Type	hero, conceptual, typography, metaphor, scene, minimal	auto
Palette	warm, elegant, cool, dark, earth, vivid, pastel, mono, retro	auto
Rendering	flat-vector, hand-drawn, painterly, digital, pixel, chalk	auto
Text	none, title-only, title-subtitle, text-rich	title-only
Mood	subtle, balanced, bold	balanced
Font	clean, handwritten, serif, display	clean

Auto-selection rules: references/auto-selection.md

Galleries

Types: hero, conceptual, typography, metaphor, scene, minimal → Details: references/types.md

Palettes: warm, elegant, cool, dark, earth, vivid, pastel, mono, retro → Details: references/palettes/

Renderings: flat-vector, hand-drawn, painterly, digital, pixel, chalk → Details: references/renderings/

Text Levels: none (pure visual) | title-only (default) | title-subtitle | text-rich (with tags) → Details: references/dimensions/text.md

Mood Levels: subtle (low contrast) | balanced (default) | bold (high contrast) → Details: references/dimensions/mood.md

Fonts: clean (sans-serif) | handwritten | serif | display (bold decorative) → Details: references/dimensions/font.md

File Structure

Output directory per default_output_dir preference:

• same-dir: {article-dir}/
• imgs-subdir: {article-dir}/imgs/
• independent (default): cover-image/{topic-slug}/

<output-dir>/
├── source-{slug}.{ext}    # Source files
├── refs/                  # Reference images (if provided)
│   ├── ref-01-{slug}.{ext}
│   └── ref-01-{slug}.md   # Description file
├── prompts/cover.md       # Generation prompt
├── cover.png              # Output image
└── collage.png            # Optional stitched overview image

Slug: 2-4 words, kebab-case. Conflict: append -YYYYMMDD-HHMMSS

Workflow

Progress Checklist

Cover Image Progress:
- [ ] Step 0: Check preferences (EXTEND.md) ⛔ BLOCKING
- [ ] Step 1: Analyze content + save refs + determine output dir
- [ ] Step 2: Confirm options (6 dimensions) ⚠️ unless --quick
- [ ] Step 3: Create prompt
- [ ] Step 4: Generate image with mage-images-gen
- [ ] Step 5: Completion report

Flow

Input → [Step 0: Preferences] ─┬─ Found → Continue
                               └─ Not found → First-Time Setup ⛔ BLOCKING → Save EXTEND.md → Continue
        ↓
Analyze + Save Refs → [Output Dir] → [Confirm: 6 Dimensions] → Prompt → Generate → Complete
                                              ↓
                                     (skip if --quick or all specified)

Step 0: Load Preferences ⛔ BLOCKING

Check EXTEND.md existence (priority: project → user):

test -f .mage-skills/mage-cover-gen/EXTEND.md && echo "project"
test -f "$HOME/.mage-skills/mage-cover-gen/EXTEND.md" && echo "user"

Result	Action
Found	Load, display summary → Continue
Not found	⛔ Run first-time setup (references/config/first-time-setup.md) → Save → Continue

CRITICAL: If not found, complete setup BEFORE any other steps or questions.

Step 1: Analyze Content

1. Save reference images (if provided) → references/workflow/reference-images.md
2. Save source content (if pasted, save to source.md)
3. Analyze content: topic, tone, keywords, visual metaphors 3.5. Extract full technical surface area: product, model, channel, tooling, memory, MCP, skills, security, operations
4. Deep analyze references ⚠️: Extract specific, concrete elements (see reference-images.md)
5. Detect language: Compare source, user input, EXTEND.md preference
6. Determine output directory: Per File Structure rules

Step 2: Confirm Options ⚠️

Full confirmation flow: references/workflow/confirm-options.md

Condition	Skipped	Still Asked
--quick or quick_mode: true	6 dimensions	Aspect ratio (unless --aspect)
All 6 + --aspect specified	All	None

Step 3: Create Prompt

Save to prompts/cover.md. Template: references/workflow/prompt-template.md

CRITICAL - References in Frontmatter:

• Files saved to refs/ → Add to frontmatter references list
• Style extracted verbally (no file) → Omit references, describe in body
• Before writing → Verify: test -f refs/ref-NN-{slug}.{ext}

Reference elements in body MUST be detailed, prefixed with "MUST"/"REQUIRED", with integration approach.

Text fidelity rule:

• when the cover includes title, subtitle, or tags, define the exact visible copy before generation
• use dedicated text zones such as top title band, subtitle strip, or tag row instead of mixing all text into one paragraph description
• keep visible text short and exact; do not let the model invent alternate titles or decorative micro-copy
• for technical covers, prefer font: clean unless the user explicitly wants a more stylized look and accepts higher text risk

Technical tutorial cover rule:

• the cover must represent the full topic surface, not just one sub-point
• when the article covers multiple technical dimensions, show them with either labeled modules, icon groups, or both
• prefer title-subtitle or text-rich when a purely visual cover would hide important technical scope
• for deployment / tooling / system articles, the cover should visibly include the core stack such as model, memory, MCP, skills, channel, and security whenever those are part of the article

Step 4: Generate Image

1. Backup existing cover.png if regenerating
2. Default image generator: Use mage-images-gen unless the user explicitly asks for another image generation skill
3. Without references: Prefer mage-images-gen --provider dashscope; if unavailable or generation fails once, retry with --provider seedream
4. Process references from prompt frontmatter:
   • direct usage → pass via --ref
   • style / palette usage → extract traits and append them to the prompt body
   • When --ref is used and no provider is forced, follow mage-images-gen ref-capable provider order: Google first, then OpenAI, then Seedream
5. Generate: Call mage-images-gen with the prompt file, output path, and aspect ratio
6. On failure: auto-retry once with the next preferred provider that matches the input mode

For text-rich or typography-led covers:

• prefer prompts that include EXACT TEXT REGIONS and NEGATIVE CONSTRAINTS
• isolate the title, subtitle, and tags into separate zones with generous padding
• forbid extra subtitles, fake UI labels, random letters, pseudo-text, and decorative micro-text
• if text is mission-critical, prefer seedream or a text-strong Qwen model over speed-first defaults
• if the first pass omits key technical points, strengthen the prompt with an explicit TECHNICAL COVERAGE CHECKLIST

Step 5: Completion Report

Cover Generated!

Topic: [topic]
Type: [type] | Palette: [palette] | Rendering: [rendering]
Text: [text] | Mood: [mood] | Font: [font] | Aspect: [ratio]
Title: [title or "visual only"]
Language: [lang] | Watermark: [enabled/disabled]
References: [N images or "extracted style" or "none"]
Location: [directory path]

Files:
✓ source-{slug}.{ext}
✓ prompts/cover.md
✓ cover.png

Image Modification

Action	Steps
Regenerate	Backup → Update prompt file FIRST → Regenerate
Change dimension	Backup → Confirm new value → Update prompt → Regenerate

Collage Mode

Use collage mode when the user wants:

• one big image containing multiple covers
• a style comparison board
• a showcase overview for README, docs, or promotion

Workflow:

1. gather the existing generated images
2. do not regenerate images if stitching alone is sufficient
3. choose a collage style:
   • showcase-dark default for promotion
   • showcase-light for polished light-background docs
   • grid-dark for compact review boards
   • grid-light for compact light-background boards
4. run scripts/create_collage.py
5. save the stitched image to the requested path

Default command:

python "${SKILL_DIR}/scripts/create_collage.py" \
  --input-dir "<dir>" \
  --output "<output>.png" \
  --style showcase-dark \
  --title "mage-cover-gen 全风格封面总览"

Composition Principles

• Whitespace: 40-60% breathing room
• Visual anchor: Main element centered or offset left
• Characters: Simplified silhouettes; NO realistic humans
• Title: Use exact title from user/source; never invent
• Text zones: Title, subtitle, and tags should each have their own stable area
• Typography reliability: For technical or professional covers, use clean printed text before stylized lettering
• Coverage: Technical covers should expose the article's main capability map, not just a generic AI symbol

Extension Support

Custom configurations via EXTEND.md. See Step 0 for paths.

Supports: Watermark | Preferred dimensions | Default aspect/output | Quick mode | Custom palettes | Language

Schema: references/config/preferences-schema.md

References

Dimensions: text.md | mood.md | font.md Palettes: references/palettes/ Renderings: references/renderings/ Types: references/types.md Auto-Selection: references/auto-selection.md Style Presets: references/style-presets.md Collage Styles: references/collage-styles.md Compatibility: references/compatibility.md Visual Elements: references/visual-elements.md Workflow: confirm-options.md | prompt-template.md | reference-images.md | collage-workflow.md Config: preferences-schema.md | first-time-setup.md | watermark-guide.md