cnlive860/microscape-poster-skill

Microscape Poster

Create fresh PNG artwork with references/original-prompt/zh-CN.md as the sole creative and aesthetic authority. This Skill is a runtime shell: it resolves delivery variables, appends them to the untouched source-brief body, executes bitmap generation, and verifies the result. It must not write a second art direction.

Authority boundary

1. Read references/original-prompt/zh-CN.md completely immediately before building every generation request.
2. Its first Markdown heading is an administrative document label, not creative content. Omit that heading from the image-generation request, then copy the entire remaining source-brief body verbatim. Do not summarize, translate, polish, expand, reinterpret, or replace that body with this file, a README, a sample, the runtime-adapter reference, or the reading translation in references/original-prompt/. That translation exists for international readers and sharing; it is never a runtime prompt alternative.
3. The source brief owns subject transformation, composition inside the design region, colour derivation, materials, impasto and paint texture, whitespace, text amount, wording logic, typographic character, and prohibitions.
4. Runtime instructions may change only: selected output mode, split strictness, final canvas ratio or pixels, placement or visibility of the reality source, target text language, and user-exact text.
5. Append all runtime instructions after the complete source-brief body. Never insert them into, or rewrite, its aesthetic paragraphs.
6. The source brief specifies a 3:4 vertical canvas and a strict 1:1 upper/lower split. Treat those as the brief's own presentation container. A mode or split block may replace that container only when the user explicitly asks; every remaining aesthetic and transformation instruction stays active.
7. Never create a generic palette, extract extra colours, lock a swatch set, invent an “aesthetic motive,” pre-compose a title, generate a copy package, or run an external semantic-reading framework. If the source brief itself asks for any of those things, let the image model perform them exactly there.
8. Samples show outcomes only. Do not copy their subject matter, colours, text, layout accidents, or aspect ratio.

Use these roles throughout:

REALITY VIEW      = the uploaded photograph, lightly graded as the source brief directs
TRANSFORMED DESIGN = the source brief's 3D impasto oil-painting microscape

The mode name is not a loose hint. For every requested asset, append exactly one mode block. Never send unused mode alternatives to the image model. Within the selected contract, let the image model decide internal scale, crop, environmental extension, whitespace, overlap and layout unless the user explicitly requests exact geometry or the source brief already fixes it.

Resolve only runtime variables

Every invocation is a new job unless the user explicitly asks to inspect, edit, continue, or reuse a named result. Repeating the same request requires fresh generation and a new task folder; an old matching file never completes a new request. Remembered delivery preferences may reduce repeated questions, but never authorize reuse of an old source, result, prompt, or task directory.

Fully specified by default

The source brief already fixes the canvas ratio (3:4 vertical), the split relationship (strict 1:1), the reality-source treatment (light exhibition grading) and the text logic (one short title plus minimal annotation). Therefore the default delivery variables are already complete:

Variable	Default when the user says nothing
--mode	top-bottom
--split	strict (exact 1:1, 50% / 50%)
--size	3:4, resolved to concrete pixels from the source
--text	prompt (the image model writes the title by the brief's own logic)
--locale	the language of the user's current request, confirmed only when genuinely ambiguous

A plain invocation such as /microscape-poster <photo> or /microscape-poster <directory> therefore generates immediately without a setup questionnaire. Ask only when a variable is genuinely unresolved or contradictory. Do not ask the user to restate what the source brief already decides.

Inline fast path

Parse parameters anywhere after the invocation and input:

/microscape-poster <source-or-directory> --mode top-bottom,design-only \
  --split strict --size 3:4,2160x2880 \
  --text prompt --locale zh-CN

• --mode: one or more of top-bottom, left-right, design-only. Repeated flags and comma-separated values accumulate; accept natural-language equivalents and all / 全部.
• --split: strict or fluid. strict enforces the exact 1:1 midpoint from the source brief; fluid releases the midpoint and lets the image model balance the two parts. Applies to top-bottom and left-right, and is ignored for design-only.
• --size: one or more of auto, source, 1:1, 3:4, 4:3, 4:5, 5:4, 2:3, 3:2, 9:16, 16:9, 21:9, 5:7, 7:5, any custom ratio, or exact WIDTHxHEIGHT. Repeated flags accumulate; accept ×.
• --text: prompt, exact, or none. Accept legacy aliases auto → prompt and custom → exact without presenting the old labels to users.
• --copy "...": exact user text; implies --text exact. Do not rewrite or translate it.
• --locale: target language, market, or locale for visible text.
• --out: explicit output root.
• --prefs: last, edit, new, off, or clear; controls whether this invocation reuses, edits, ignores, suppresses, or clears the family-wide remembered delivery preference.

Explicit parameters override ambiguous prose. Multi-value parameters accumulate and deduplicate in user order; single-value parameters use the last explicit value. If every required variable is resolved, skip preflight and generate. If values are partial, ask only for unresolved variables. Ask about a direct contradiction such as --text none with --copy.

Remembered preference gate

After parsing current prose and inline parameters, read references/runtime-preferences.md completely and follow it before the ordinary preflight. When unresolved settings remain and a valid previous record exists, offer exactly three clear routes: reuse, reuse and edit, or fresh configuration. A fully specified current invocation remains a true fast path and skips this question.

The remembered record is shared across the XXD Panel family because these are common delivery variables, not aesthetic choices. Current explicit requirements always win. Never remember exact copy, source paths, generated content, model routes, credentials, or secrets. Once the current settings are fully resolved, save only the safe delivery fields through scripts/panel_preferences.py, unless the user selected --prefs off or asked not to remember the invocation.

Directory batch intake

The source brief requires one independent poster per photograph, so batch is a first-class path. A readable directory supplied as the source is explicit batch intent. Enter batch processing immediately; do not ask whether the user wants a batch and do not show an unrelated mode menu before inventory.

1. Recursively inventory supported raster files (.png, .jpg, .jpeg, .webp, .heic, .heif, .avif, .tif, .tiff, .bmp) case-insensitively. Respect an explicit top-level-only request or user exclusions.
2. Ignore hidden files and hidden directories, non-images, this Skill's generated task folders, and output roots inside the supplied tree. Do not follow a symbolic link whose resolved target escapes the supplied directory.
3. Use stable natural ordering by relative path. Report the discovered count and recursive scope before generation. Identify unreadable or undecodable candidates; never silently skip them. If no supported images exist, stop without creating an empty task directory.
4. Build one queue item per discovered source. Every item uses this same style brief unchanged; never select, blend, or switch to another style during a batch.
5. Resolve shared mode, split, size, text and locale settings once for the whole batch. Parameters and clear prose still skip questions. Resolve auto and source per image because orientations may differ. Before execution, state the input count, shared settings, per-image exceptions, and total expected output count.
6. Treat every source as a logically isolated generation job: read the source brief afresh, construct its prompt independently, and never carry another image's content, inferred meaning, wording, prompt, or result into it. Each poster is self-contained; never merge several sources into one sheet.
7. --text prompt generates source-grounded wording independently for each image. --text none applies to all images. A single --copy deliberately applies the same exact text to every image; when exact text differs, accept an explicit relative-path-or-filename → exact-text mapping and verify every intended source before generation. Never reuse one mapped caption for another source.
8. A failed source or asset must be named and reported without silently dropping later queue items. Apply the normal single-asset retry rule only to the failed output, continue with the remaining queue, and finish with succeeded/failed counts and paths.

One batch invocation is one physical task directory even though its queue items are logically isolated. Do not create a task directory per source.

Capability-adaptive preflight

Do not switch the user's session into Plan mode merely to obtain a question UI. A Skill describes behaviour but cannot create UI capabilities that the host has not exposed. Detect the actual question-tool schema and follow this order:

1. Real multi-select tool available — for example Claude Code AskUserQuestion with multiSelect: true: use genuine checkbox questions for modes and sizes. Use single-select questions for split strictness and text mode. Do not print a redundant numbered menu after showing the form.
   • First form: modes (top-bottom, left-right, design-only) with multiSelect: true; split (严格 1:1, 自由比例) as single-select; text mode as single-select.
   • When a size question is genuinely needed, offer 3:4（简报默认）, 跟随原图, 常用比例, 自定义. When 常用比例 is selected, show real checkbox groups for all concrete ratios, split only as required by host option limits: square 1:1; portrait 3:4, 4:5, 2:3, 9:16, 5:7; landscape 4:3, 5:4, 3:2, 16:9, 21:9, 7:5. Accumulate selections across groups. When 自定义 is selected, collect one or more ratios or exact pixel targets through the host's free-input/Other path.
2. Only a mutually exclusive question tool is available — for example Codex request_user_input: use it only for genuinely single-choice fields such as text mode, split strictness, or the size-entry route. Never represent modes or concrete sizes as a single-select when the user may choose several. Collect those multi-value fields with the two-round combination input below. Do not claim that a single-choice card is a checkbox.
3. No interactive question tool is available: use the same two-round combination input below. It is typed multi-value input, not a clickable form. Never draw Markdown - [ ] boxes or other fake controls.

Inline parameters and clear natural language always take priority. Skip every field already resolved. When all required values are present, skip every question and generate immediately.

Two-round combination-input fallback

First round — modes and split:

请选择一个或多个成品类型：

1. 上下对照（原图在上，厚涂微景观在下）
2. 左右对照（原图在左，厚涂微景观在右）
3. 只要微景观（原图仅作参考，不出现在成品中）

上下／左右采用哪种分割？
A. 严格 1:1（各占 50%，原始简报的默认要求）
B. 自由比例（由画面自行平衡两部分）

可回复：1，A｜1+3，B｜全部，A

Second round — only when the size is genuinely unresolved, ask size and text together:

请选择尺寸，可多选：

1. 3:4 竖版（原始简报的默认构图）
2. 跟随原图
3. 常用比例（可直接写 4:5、9:16 等一个或多个比例）
4. 自定义（输入一个或多个比例／准确像素）

请选择文字方式：

A. 模型根据原始简报生成标题与极少量注释（注明语言）
B. 使用我的准确文字（发送原文并注明语言）
C. 不要文字

可回复：尺寸 1；文字 A，简体中文
可回复：尺寸 4:5、16:9；文字 B，准确文字「……」，简体中文

Do not decide wording outside the source brief. For option A, provide only the target language to the image model; the image model follows the source brief's existing text logic. For option B, pass the user's characters verbatim and add no other copy. For option C, prohibit all visible text and pseudo-text.

Do not infer language or market from a person's appearance, name, clothing, scene, filename, metadata, signage, or the language used to operate the Skill. Resolve it explicitly whenever text is requested. Use natural target-language shaping, direction, punctuation, spacing, and line breaking. For Arabic, preserve connected forms and right-to-left text flow without indiscriminately mirroring the artwork.

Size resolution

• The source brief specifies 3:4 vertical, so 3:4 is the default, not a silent fallback. Resolve it to concrete pixels from the source and state the result. There is no separate “recommended ratio” step.
• auto means: honour the source brief's 3:4 default unless the source orientation and the user's stated use make another ratio clearly better; then recommend and state that ratio and its pixels.
• source means the source photograph's aspect for the whole requested ordinary output, overriding the brief's 3:4.
• Exact pixels override a ratio.
• Every distinct aspect ratio is a separate complete-canvas composition from the same source and the same verbatim style brief. Never crop one ratio from another. Multiple resolutions sharing one aspect may be exported from the highest-quality approved composition.
• A size set applies to every selected ordinary mode unless the user maps sizes per mode.
• Before generation, state the resolved modes, split strictness, concrete sizes, text mode and locale, and total output count. Do not ask for another confirmation when they are complete and consistent.

Build the generation prompt

For each distinct asset, concatenate exactly:

[VERBATIM SOURCE-BRIEF BODY FROM references/original-prompt/zh-CN.md,
EXCLUDING ONLY ITS ADMINISTRATIVE FIRST MARKDOWN HEADING]

[COMMON DELIVERY PREAMBLE]
[EXACTLY ONE SELECTED MODE BLOCK]
[EXACTLY ONE TEXT BLOCK]
[USER'S OTHER EXPLICIT REQUIREMENTS, IF ANY]

Use this common preamble:

MODE-SPECIFIC DELIVERY OVERRIDE — CURRENT ASSET

This block is the final authority only for the current presentation mode,
split relationship, reality-source visibility and final canvas. It replaces
the source brief's own statements about the 3:4 container and the upper/lower
split only where the selected block says so explicitly.

Every source-brief instruction about the transformation's visual language,
subject identity, impasto and paint material, colour derivation, internal
composition, whitespace, text character and typography remains authoritative.

REALITY VIEW means the faithful photograph, lightly graded as the source brief directs.
TRANSFORMED DESIGN means the source brief's 3D impasto oil-painting microscape.

FINAL CANVAS: <resolved ratio and/or exact WIDTHxHEIGHT>
EXACT PANEL GEOMETRY: ONLY WHEN THE SPLIT IS STRICT OR THE USER EXPLICITLY REQUESTS IT
ONE POSTER PER SOURCE: NEVER COMBINE SEVERAL SOURCES INTO ONE SHEET

Colour follows the source brief's own re-derivation logic exactly: take the
brightest, most vivid and most living colours from the reality view rather than
averaging them. Unless the user explicitly requests a colour change, do not add,
replace, summarize, or re-plan any palette.

Append exactly one mode block; do not include the others.

Top-bottom, strict split — the source brief's default:

OUTPUT MODE: TOP_BOTTOM
SPLIT CONTRACT: STRICT_1_1

Create one complete canvas divided into exactly two horizontal halves of equal
height. The REALITY VIEW occupies the upper 50% and the TRANSFORMED DESIGN
occupies the lower 50%. The boundary sits at the exact vertical midpoint of the
canvas, and each half spans the full canvas width. Do not shift, rebalance,
approximate or crop this relationship; the two halves are equal in height to
the pixel row.

REALITY VIEW (upper half): the faithful photograph carrying only the source
brief's subtle high-end photographic grading. Preserve subject identity,
structure, proportion, authentic texture, natural light and existing colour
atmosphere. Sky, ground or environment may be extended only to fill the half;
never stretch, distort or alter the subject.

TRANSFORMED DESIGN (lower half): the source brief's 3D impasto oil-painting
microscape, composed entirely within this half, keeping its generous warm-white
whitespace and centred or slightly off-centre diagonal main axis.

Top-bottom, fluid split:

OUTPUT MODE: TOP_BOTTOM
SPLIT CONTRACT: FLUID

Create one complete canvas whose dominant structure is two primary horizontal
parts: the REALITY VIEW above and the TRANSFORMED DESIGN below. Together they
organize the composition across its full width. Let the image model determine
their visual proportion and each part's internal crop, extension, whitespace
and typography from the source, source brief and final canvas.

Left-right, strict split:

OUTPUT MODE: LEFT_RIGHT
SPLIT CONTRACT: STRICT_1_1

Create one complete canvas divided into exactly two vertical halves of equal
width. The REALITY VIEW occupies the left 50% and the TRANSFORMED DESIGN
occupies the right 50%. The boundary sits at the exact horizontal midpoint, and
each half spans the full canvas height. Do not shift, rebalance, approximate or
crop this relationship. All visible material, including typography, belongs
within this left-right structure.

Left-right, fluid split:

OUTPUT MODE: LEFT_RIGHT
SPLIT CONTRACT: FLUID

Create one complete canvas whose dominant structure is two primary vertical
parts: the REALITY VIEW on the left and the TRANSFORMED DESIGN on the right.
Together they organize the composition from the top edge to the bottom edge;
all visible material, including typography, belongs within this left-right
structure. Let the image model determine asymmetric widths and each part's
internal crop, extension, whitespace and typography.

Design-only:

OUTPUT MODE: DESIGN_ONLY
SPLIT CONTRACT: NOT_APPLICABLE

Create one full-canvas artwork entirely in the TRANSFORMED DESIGN language.
Use the REALITY VIEW only as the non-visible source of identity, structure,
relationships, colour logic and facts. Every visible visual element must be
part of the source brief's impasto microscape rather than an untransformed
presentation of the source photograph.

Append exactly one text block after the selected mode block. If the user has other explicit requirements, append those verbatim after the text block at the very end.

Prompt-generated text:

TEXT MODE: ORIGINAL_PROMPT_GENERATED
TEXT LANGUAGE: <resolved language or locale>

The image model must generate any wording by following the original brief's
existing text logic: one short title drawn from the subject's identity,
location, mood or symbolic meaning, plus a very small amount of subtext,
numbering or micro-annotation. Every visible word must arise naturally from the
current source image's content, atmosphere or implied meaning as interpreted
through that logic. Anything presented as factual or documentary information
must come from user-supplied, visibly readable or otherwise verified source
facts; when those facts are unavailable, use poetic non-factual wording. The
runtime shell is never a source of visible copy. Keep typography delicate,
restrained and generously spaced.

User-exact text:

TEXT MODE: USER_EXACT
TEXT LANGUAGE: <resolved language or locale>
TEXT: 「<user's exact characters>」

Use the supplied text verbatim. Do not rewrite, translate, spell-correct, or add
any other wording. Typography and placement still follow the original brief.

Text-free:

TEXT MODE: NONE
Render no letters, characters, numbers, logos, captions, labels, or pseudo-text anywhere.

If the user explicitly changes colour or another style variable, append that exact request at the very end, after the text block, and identify it as a user override. Do not elaborate it.

Immediately before generation, verify that the constructed prompt contains exactly one OUTPUT MODE: line, exactly one SPLIT CONTRACT: line, and no instructions from an unselected mode.

Bitmap execution

• Prefer GPT Image 2 whenever the host's built-in image capability or an already configured compatible route exposes it.
• Also support Seedance 5.0 Pro, Nano Banana Pro (Gemini Image Pro), Nano Banana 2 (Gemini Image Flash), or another compatible bitmap model only when it can preserve the reference, requested canvas, language, and multi-reference needs. Changing the model must not change this workflow or the prompt-authority boundary.
• Judge readiness by an actual image-capability check, not one missing tool or environment variable. Never name or expose a provider, endpoint, credential, header, account, route, or secret.
• If the built-in image tool is exposed, follow the installed imagegen Skill and make one generation/edit call per distinct asset. A batch of eight photographs produces eight posters, not one contact sheet.
• If built-in generation is not exposed, run python3 scripts/configured_imagegen.py probe. Its sanitized result is the only allowed diagnostic surface. If ready, use edit with the source and a private prompt file; use generate only when no image reference genuinely exists.
• Do not echo a credential or full prompt in shell history or logs. Do not inspect configuration files manually. Do not modify provider, account, billing, credential, or global routing settings unless the user explicitly requests that separate change.
• If no compatible route is verified, ask the user to enable a suitable image tool or voluntarily provide an API key for the task. Never ask them to expose an existing secret, and never assert that a key is missing without a trusted sanitized result.
• Generate finished raster imagery. SVG, HTML, CSS, Canvas, diagrams, and programmatic vector drawing are not substitutes.

Use one complete-canvas generation per output. Give the image model the source, complete source-brief body, common preamble, one selected mode block, one text block and final canvas in one request; do not pre-crop the source or generate separate halves. The model decides how to preserve the important subject and context inside the selected mode contract. Retry a failed complete canvas once by restating only a meaningful failed content or delivery constraint.

Use scripts/compose_panel.py only when the user explicitly requests pixel-exact panel geometry or pixel-identical source preservation — for example, when the upper half must be the untouched source file at full fidelity and the lower half is a separately generated microscape. The script may crop, paste, size and audit raster files; it must never invent the artwork or judge style. In that two-stage path, generate the microscape half first as an independent 3:2 half-canvas artwork from the same brief, then compose it beneath the source with --layout top-bottom and an even output height.

Note that --audit is a heuristic: it locates the strongest gradient row, so it reports a false seam whenever the composed half contains its own strong internal edge. Treat it as a sanity hint, never as the verdict. The composited geometry is authoritative because --layout top-bottom enforces an even height and writes an exact half split; the script itself reports split exactly H/H.

Source and output isolation

Use only sources attached to the current invocation, explicit image paths, an explicitly supplied input directory, or a prior source explicitly identified by the user as “the same image.” Scan a directory only under the directory-batch rules above; never scan Desktop, workspace roots, output folders, or unrelated directories for a substitute. Historical outputs and sample assets are not inputs unless explicitly named.

Write every selected final PNG directly inside the fresh task directory. The task directory is the only grouping layer:

~/Desktop/xxd/microscape-poster/<fresh-task>/
├── source-001-kashgar-top-bottom-strict-3x4-1536x2048.png
├── source-001-kashgar-design-only-3x4-1536x2048.png
├── source-002-dunhuang-top-bottom-strict-3x4-1536x2048.png
└── source-003-sea-top-bottom-fluid-3x4-1536x2048.png

Use zero-padded source-order prefixes plus a sanitized source stem for multiple inputs, for example source-001-street and source-002-flower. Follow with the mode, then the split contract when it is not strict, then a collision-safe size label. Normalize ratio separators to x in filenames and include exact output pixels whenever they help distinguish requested variants. Do not create source, mode, size, or split subdirectories, and do not create empty directories for unselected modes.

--out replaces the root but not fresh-task isolation. Reserve a collision-safe task name before generation. Do not create an automatic collage, overview, mockup, or combined preview. Return absolute PNG paths in source order, then mode order top-bottom → left-right → design-only.

Acceptance gate

Inspect every final PNG at full size and thumbnail size. Accept only when:

• it is a fresh result from the correct current source;
• mode, split contract, whole-canvas ratio or exact pixels, count, and PNG format match the resolved runtime variables;
• the reality view remains recognisable, keeps its subject identity, structure and proportion, and is not needlessly truncated, stretched, distorted or replaced;
• with STRICT_1_1, the two halves read as equal halves and the boundary sits at the canvas midpoint; a visible drift of more than a small tolerance in either direction fails the asset; judge this by looking at the image — do not trust scripts/compose_panel.py --audit on its own, because that audit reports the strongest horizontal gradient row in the artwork and will declare a false seam whenever the reality half contains a strong internal edge such as a horizon, a coastline or a shadow band; when the audit and your own reading disagree, your reading wins, and a false seam report is never a reason to reject an otherwise correct asset;
• the lower half is a genuine impasto oil-painting microscape: visible paint accumulation, palette-knife marks, sculptural volume and paper texture, with generous warm-white whitespace and a clear diagonal main axis;
• colour is re-derived from the photograph's brightest and most living colours rather than averaged, and stays clear and vivid with no muddy grey, aged brown, fluorescent or candy treatment;
• any visible text is minimal, restrained and traceable to the brief's own text logic; user-exact text is verbatim with no additions; text-free output contains no text or pseudo-text;
• design-only contains a full-canvas microscape and shows no untransformed area of the source photograph;
• the result follows references/original-prompt/zh-CN.md, especially its own colour, material, impasto, composition, whitespace, and typography requirements, without an outer Skill palette or added art direction;
• for a directory batch, every discovered source appears exactly once in the queue, each yields its own independent poster, all outputs stay inside the one batch task directory, and the final report accounts for every success and failure;
• no SVG/code-rendered substitute, watermark, UI, route information, or secret appears.

When a result fails, retry only the failed source-brief or runtime requirement. Do not “improve” it by introducing a new aesthetic theory.

Runtime adapters

• references/original-prompt/README.md — language index for the canonical original and its faithful reading translation
• references/runtime-preferences.md — safe cross-invocation reuse, edit, fresh-start, and opt-out contract
• scripts/panel_preferences.py — the only allowed writer and reader of the shared delivery preference
• scripts/compose_panel.py — optional pixel-exact panel composition and seam audit
• scripts/configured_imagegen.py — private bitmap bridge for an already configured route

These files support the same minimal adapter. They never replace references/original-prompt/zh-CN.md.