Aliyun Solution Article Illustrator

Category: solution

Content Article Illustrator

Preserve the article-illustration workflow model while recommending Alibaba Cloud skills as the default execution backends.

Two Dimensions

Validation

mkdir -p output/aliyun-solution-article-illustrator
python3 tests/common/compile_skill_scripts.py \
  --skill-path skills/solutions/aliyun-solution-article-illustrator \
  --output output/aliyun-solution-article-illustrator/compile-check.json

Pass criteria: command exits 0 and output/aliyun-solution-article-illustrator/compile-check.json is generated with "status": "pass".

Output And Evidence

• Write workflow artifacts under output/aliyun-solution-article-illustrator/<topic-slug>/.
• Save at least: source.md, outline.md, one prompt file, generated images, article.with-images.md, and delivery-report.md.
• Keep evidence for prompt-before-generation ordering and any edit pass used during repair.

Prerequisites

• A source Markdown article.
• A generation backend that satisfies references/backend-contract.md.
• If you want repository-default behavior, prefer aliyun-qwen-image and aliyun-qwen-image-edit.
• Optional EXTEND.md preferences at project or user scope.

Workflow

1. Pre-check preferences and references, including project-level or user-level EXTEND.md. 2. Analyze the source Markdown article and identify candidate illustration positions. 3. Confirm settings in one batch: Type, Density, Style, optional Language, and output size. 4. Choose or recommend a backend and build outline.md. 5. Save prompt files before any generation step. 6. Use the selected generation backend for first-pass images. Recommend aliyun-qwen-image by default. 7. If needed, use the selected edit backend for one repair pass per image. Recommend aliyun-qwen-image-edit by default. 8. Write article.with-images.md with relative images/... Markdown links. 9. Save evidence and produce delivery-report.md.

Minimal Executable Run

python3 skills/solutions/aliyun-solution-article-illustrator/scripts/run_workflow.py \
  --source path/to/article.md \
  --output-dir output/aliyun-solution-article-illustrator/example-run \
  --generation-backend mock

State Gates

• drafted: source article and initial outline exist
• confirmed: user settings, preferences, and backend choice are confirmed
• generated: prompt files and first-pass images exist
• validated: artifact structure and Markdown insertion pass checks
• delivered: final article and report are written

References

• Detailed workflow: references/workflow.md
• Usage examples: references/usage.md
• Style system: references/styles.md
• Backend contract: references/backend-contract.md
• Prompt construction rules: references/prompt-construction.md
• Output contract: references/output-spec.md
• Validation and test expectations: references/test-plan.md
• Config setup: references/config/first-time-setup.md
• Preferences schema: references/config/preferences-schema.md
• Source references: references/sources.md
• Helper scripts: scripts/load_preferences.py, scripts/validate_inputs.py, scripts/build_outline.py, scripts/collect_evidence.py

System Prompt

Preserve the article-illustration workflow order:

1. load preferences 2. analyze article structure 3. confirm Type and Style 4. build outline 5. save prompt files 6. generate images 7. optionally repair images once 8. write final illustrated Markdown

Do not skip prompt-file creation before image generation.

Backend Contract

This solution skill recommends Alibaba Cloud backends by default, but does not hard-bind to them.

Recommended Defaults

• Generation backend: aliyun-qwen-image
• Edit backend: aliyun-qwen-image-edit

Generation Backend Requirements

Inputs:

• saved prompt file content
• optional reference images
• requested size or aspect
• optional style hint

Outputs:

• image file path or retrievable image URL
• metadata that can be saved as evidence

Edit Backend Requirements

Inputs:

• source image
• edit instruction or saved edit prompt
• optional mask or local-edit parameters

Outputs:

• edited image file path or retrievable image URL
• metadata that can be saved as evidence

First-Time Setup

If no preference file exists, create one of these:

• project-level: .alicloud-skills/aliyun-solution-article-illustrator/EXTEND.md
• user-level: $HOME/.alicloud-skills/aliyun-solution-article-illustrator/EXTEND.md

The project-level file overrides the user-level file.

Suggested starting template:

---
version: 1
watermark:
  enabled: false
  content: ""
  position: bottom-right
  opacity: 0.7
preferred_style:
  name: null
  description: ""
language: null
default_type: null
default_density: null
default_output_dir: null
custom_styles: []
---

Preferences Schema

Supported preference fields:

---
version: 1

watermark:
  enabled: false
  content: ""
  position: bottom-right
  opacity: 0.7

preferred_style:
  name: null
  description: ""

language: null
default_type: null
default_density: null
default_output_dir: null

custom_styles: []
---

Field Reference

• version: schema version.
• watermark.enabled: whether watermarking should be enabled by default.
• watermark.content: watermark text or handle.
• watermark.position: default placement such as bottom-right.
• watermark.opacity: opacity hint for downstream generation or post-processing.
• preferred_style.name: preferred built-in or custom style name.
• preferred_style.description: notes or override guidance for the preferred style.
• language: preferred image-text language.
• default_type: preferred illustration type.
• default_density: preferred image density.
• default_output_dir: preferred output location policy.
• custom_styles: optional list of custom style definitions.

Output Directory Options

• same-dir
• imgs-subdir
• illustrations-subdir
• independent

Custom Style Shape

Each custom style may include:

- name: my-style
  description: "Short description"

The current repository implementation records custom style names in the preference summary. Deeper style attributes can be added later without changing the loader contract.

Preferences are optional. If absent, the workflow must still proceed with explicit confirmation.

Output Specification

Root Path

output/aliyun-solution-article-illustrator/<topic-slug>/

Required Files

source.md
outline.md
article.with-images.md
delivery-report.md
workflow-run.json
artifacts.json
prompts/
images/
edits/

Naming Rules

• Source article: source.md
• Final illustrated article: article.with-images.md
• Prompt files: prompts/NN-<slug>.md
• Image files: images/NN-<slug>.png
• Edit records: edits/NN-<slug>.md

Markdown Rule

Use relative links only:

![alt text](images/01-cover.png)

Evidence Rules

• Keep artifact listings in the output root.
• Record which outline item produced each image.
• If an image was edited, record the reason and replacement path.
• If preferences were loaded, save a preference summary artifact for reproducibility.

Prompt Construction

Rules

• Save prompt files before any image generation step.
• Each prompt must map back to one outline.md entry.
• Use article-specific terms, concepts, and labels instead of generic filler.
• Keep prompts explicit about what to show and what to avoid.
• Keep Type and Style as separate fields so the workflow can combine them consistently.
• Use structured sections so prompts remain inspectable and reusable across backends.

Required Prompt Structure

Each prompt file should use a short header plus structured body sections:

Title:
Target Section:
Type:
Style:
Visual Goal:
References:
Layout:
ZONES:
LABELS:
COLORS:
STYLE NOTES:
ASPECT:
Prompt:
Negative Prompt:

Section Requirements

• Title: short human-readable title.
• Target Section: where the image will be inserted.
• Type: one workflow type such as infographic or flowchart.
• Style: one selected style such as notion or blueprint.
• Visual Goal: why this image exists.
• References: optional saved reference images or extracted notes.
• Layout: overall composition such as grid, top-down, or split view.
• ZONES: named visual regions with concrete content.
• LABELS: article-specific terms, numbers, metrics, or short quotes.
• COLORS: semantic colors or palette hints.
• STYLE NOTES: line treatment, rendering guidance, texture, mood.
• ASPECT: ratio or size target.
• Prompt: final generation prompt body.
• Negative Prompt: exclusions or quality guardrails.

Reference Usage Rules

• Only include file-backed references if the files actually exist.
• Use direct when the reference should materially shape the output composition.
• Use style when only the aesthetic language should carry over.
• Use palette when only colors should carry over.
• If no file is saved, describe extracted characteristics in prompt text instead of pretending there is a file-backed reference.

Type-Specific Guidance

Infographic

• Prefer Layout, ZONES, and LABELS with concrete data.
• Use COLORS semantically, not decoratively.

Scene

• Emphasize atmosphere, focal point, and emotional intent in STYLE NOTES.

Flowchart

• Use Layout for directionality and ZONES for ordered steps.

Comparison

• Split ZONES clearly between the two sides.

Framework

• Use ZONES and LABELS to show conceptual relationships.

Timeline

• Keep chronological order explicit in ZONES and LABELS.

Prompt Quality Requirements

• ZONES must not be vague; each zone should describe specific visual content.
• LABELS should use real article language whenever possible.
• COLORS should reflect meaning, brand, or category.
• STYLE NOTES should reinforce the selected style without overwriting Type.
• Prompt should summarize the structured sections, not replace them.
• References should clearly state direct, style, or palette usage when a reference is present.

Repair Prompt Rules

• Repair prompts must describe what changes and what stays fixed.
• Limit automated repair to one pass per image.
• Save repair prompts under edits/ or reference them from the edit record.
• Repair prompts should restate the original Type, Style, and preserved elements.

Sources

• Downstream image generation skill: skills/ai/image/aliyun-qwen-image/
• Downstream image editing skill: skills/ai/image/aliyun-qwen-image-edit/
• Repository standard template: docs/standards/skill-template.md
• Approved design: docs/plans/2026-03-06-solutions-composite-skill-design.md
• External workflow reference: ../baoyu-skills/skills/baoyu-article-illustrator/

Styles

Type and Style are separate axes.

Types

• infographic
• scene
• flowchart
• comparison
• framework
• timeline

Styles

• notion
• warm
• minimal
• blueprint
• watercolor
• editorial

Detailed notes:

• references/styles/notion.md
• references/styles/warm.md
• references/styles/minimal.md
• references/styles/blueprint.md
• references/styles/watercolor.md
• references/styles/editorial.md

Type x Style Compatibility Matrix

✓✓ = highly recommended, ✓ = compatible, ✗ = not recommended

Auto Selection By Type

Auto Selection By Content Signals

Combination Notes

infographic + blueprint

• Best for technical and architectural articles.
• Prefer grid layouts, schematic lines, and high information density.

scene + warm

• Best for narrative and reflective content.
• Prefer soft gradients, inviting tone, and emotional clarity.

flowchart + notion

• Best for approachable tutorials and SaaS/productivity explainers.
• Prefer simple step containers and minimal decoration.

comparison + editorial

• Best for balanced side-by-side analysis.
• Prefer clear separators, strong headings, and concise labels.

framework + minimal

• Best for conceptual models where clarity matters more than ornament.
• Prefer clean nodes, whitespace, and restrained color usage.

timeline + watercolor

• Best for human, historical, or growth-oriented sequences.
• Prefer flowing progression and softer transitions.

The style list is intentionally smaller than the external reference skill in the first repository version. Additional style reference files can be added without changing the workflow contract.

blueprint

Description

Technical schematic style for systems, frameworks, and information-dense articles.

Visual Characteristics

• grid-aligned composition
• precise lines and containers
• diagram-first thinking
• high readability under dense labeling
• engineering or architecture feel

Best For

• system architecture
• engineering explainers
• API or infra diagrams
• technical frameworks and process maps

Prompt Hints

• specify layout direction and node relationships
• include structured labels and semantic color mapping
• prefer clarity over decorative realism

editorial

Description

Magazine-style explanatory visual language for balanced analysis and polished storytelling.

Visual Characteristics

• strong visual hierarchy
• clear headings and dividers
• polished infographic feel
• balanced typography and labels
• suitable for modern publication layouts

Best For

• explainers
• side-by-side comparisons
• journalism-style summaries
• timelines and feature overviews

Prompt Hints

• keep sections crisp and readable
• use dividers and headings intentionally
• combine polish with information density

minimal

Description

Highly restrained visual style focused on conceptual clarity and whitespace.

Visual Characteristics

• sparse elements
• high whitespace usage
• restrained palette
• low ornamentation
• emphasis on hierarchy through spacing

Best For

• conceptual frameworks
• abstract principles
• concise comparison views
• executive-level communication

Prompt Hints

• remove decorative extras
• keep zones simple and balanced
• use color only when it adds meaning

notion

Description

Minimal, approachable, hand-drawn product-illustration style inspired by knowledge-sharing and SaaS content.

Visual Characteristics

• simple line work
• rounded shapes
• quiet neutral backgrounds
• restrained accent colors
• friendly product-thinking tone

Best For

• SaaS explainers
• productivity workflows
• approachable tutorials
• knowledge cards and summaries

Prompt Hints

• use soft outlines and clear whitespace
• keep labels concise
• prefer calm, neutral composition over dramatic scenes

warm

Description

Friendly and human-centered illustration style for narrative, reflective, and educational content.

Visual Characteristics

• soft gradients
• inviting color temperature
• organic shapes
• gentle emotional tone
• more atmosphere than technical precision

Best For

• stories and journeys
• reflective writing
• lifestyle and education
• community or people-centric explainers

Prompt Hints

• prioritize mood and emotional clarity
• avoid overly technical diagram language
• use lighting and posture to convey feeling

watercolor

Description

Soft artistic style with painterly transitions and atmospheric warmth.

Visual Characteristics

• blended edges
• soft texture
• lighter structural rigidity
• expressive color transitions
• more mood than precision

Best For

• travel and lifestyle
• historical or reflective timelines
• emotional scenes
• creative and human-centered storytelling

Prompt Hints

• favor atmosphere and motion over hard geometry
• keep labels minimal
• use soft transitions and a lighter visual rhythm

Test Plan

The smoke test for this skill should verify:

• required frontmatter exists
• helper scripts compile
• load_preferences.py resolves project-first fallback correctly
• preference summary captures watermark, output-dir, and custom-style metadata when present
• preference-loading guidance exists
• Type and Style are distinct concepts in the docs
• styles docs include a Type x Style compatibility matrix and auto-selection guidance
• backend recommendation is documented without hard-binding
• a minimal outline can be generated
• prompt docs require structured sections such as ZONES, LABELS, COLORS, and ASPECT
• workflow and prompt docs explain direct, style, and palette reference usage
• prompt files exist before images
• article.with-images.md is generated
• inserted image links use images/... relative paths
• evidence is written under output/aliyun-solution-article-illustrator-test/

Usage

Use this skill when the user asks to:

• illustrate an article
• add images to a Markdown article
• generate article visuals with consistent Type and Style
• produce an illustrated Markdown deliverable

Typical flow:

1. load preferences from EXTEND.md if present 2. confirm Type, Density, Style, and optional Language 3. choose or accept a recommended backend 4. create outline.md 5. save prompt files under prompts/ 6. generate images through the selected backend 7. optionally repair weak images once through the selected edit backend 8. write article.with-images.md

Executable example:

python3 skills/solutions/aliyun-solution-article-illustrator/scripts/run_workflow.py \
  --source path/to/article.md \
  --output-dir output/aliyun-solution-article-illustrator/example-run \
  --generation-backend mock

Workflow

1. Pre-check

• If the user provides reference images, save them under references/ before using them in prompts.
• Only treat a reference as file-backed if it is actually saved on disk.
• Look for project-level EXTEND.md at .alicloud-skills/aliyun-solution-article-illustrator/EXTEND.md.
• Look for user-level EXTEND.md at $HOME/.alicloud-skills/aliyun-solution-article-illustrator/EXTEND.md.
• Load and summarize preferences if present.
• Use scripts/load_preferences.py when you need a reproducible preference summary artifact.
• If no preference file exists, continue with explicit confirmation and reference config/first-time-setup.md.
• Choose a topic slug for the output directory.

2. Analyze

• Identify article sections, key claims, and paragraphs that benefit from visual support.
• Prefer images that clarify structure, concepts, comparisons, or narrative transitions.
• Record each candidate insertion point in outline.md.
• If references exist, classify them as direct, style, or palette usage.

3. Confirm Settings

Confirm these settings in one batch:

• illustration type
• density
• style
• optional language
• output size
• generation backend
• edit backend
• reference usage mode when reference images are available

4. Build Plan

• Create outline.md from the template.
• Create one prompt file per image under prompts/.
• Prompt files must be saved before any image generation step.
• Recommend Alibaba Cloud backends by default, but allow replacement if the backend contract is satisfied.
• If a saved reference image exists, record whether it is used as direct, style, or palette.

5. Generate Assets

• Generate first-pass images with the selected backend.
• Save images under images/ using ordered filenames.
• Pass reference images only when the selected backend supports them and the files are actually saved.

6. Review And Repair

• Review each image against its outline entry.
• If needed, run one repair pass with the selected edit backend.
• Save repair intent and output under edits/.

Reference Usage Modes

• direct: use the saved reference image as a strong visual reference when the target output is closely aligned.
• style: extract visual characteristics from the reference and describe them in prompt text.
• palette: extract colors only and express them in COLORS.

7. Finalize Delivery

• Write a new file named article.with-images.md.
• Insert relative Markdown image links such as ![alt text](images/01-cover.png).
• Do not overwrite source.md.
• Write delivery-report.md summarizing generated artifacts and any repair pass.

Delivery Report

• Topic Slug:
• Source File:
• Final Article:
• Prompt Files:
• Images:
• Edited Images:
• Notes:

Outline Template

Illustration 1

• Position:
• Purpose:
• Visual Content:
• Prompt File:
• Image File:
• Edited:

Prompt Template

Title: Target Section: Type: Style: Visual Goal: References: Layout: ZONES:

• Zone 1:
• Zone 2:

LABELS:

• Term 1:
• Term 2:

COLORS:

• Primary:
• Accent:

STYLE NOTES: ASPECT: Prompt: Negative Prompt: