soia-pkm-cover-image

PKM publishing chain (compose -> publish-*) in thecover generation step: generate a bitmap cover for an article that has already been written or is about to be published; in the WeChat Official Account scenario, the output can be fed directly to soia-pkm-publish-wechat-draft 's --cover parameter. This skill only producesone cover bitmap(in-article illustrations/images belong to the v2 roadmap, see the end of the document); it does not do layout, does not publish, and does not touch account credentials.

Customer-readable description

What this skill can do

Customer wants	Skill will do	Customer can see
Pair a cover for a WeChat Official Account/X/Xiaohongshu article	Analyze content → recommend five-dimensional parameters (type/palette/rendering/text/mood) and aspect ratio → confirm → resolve generation backend → write prompt to disk → generate	Confirmation checklist, final prompt file,`cover.png`, completion receipt
Regenerate in a different style	Keep the old version, write a new prompt file, regenerate only, do not trace or modify text on the old image	Comparison of the artifact paths of the old and new versions
Backend unavailable (codex not installed / not logged in)	Stop generation, clearly state what is missing and how to complete it, never degrade to code-drawn images pretending to be bitmaps	Missing-item explanation + installation/login guidance

How customers use it

Provide: the article'sexact title(must not be fabricated or rewritten by this skill), topic/key points, target publishing channel (WeChat Official Account / X / Xiaohongshu, determines the default aspect ratio).
After analyzing the content, the Agent recommends five-dimensional parameters and aspect ratio, and hands them to the customer for confirmation together with the "confirmation gate"—unless the customer has already explicitly said "generate directly"/ inthis current sentence,--quick。
Backend resolution (see the "Backend Resolution" section): if the current message specifies a backend, use it; otherwise detect the codex CLI; if neither is satisfied, stop and ask the customer, do not silently degrade.
Before generation, write the final prompt to disk at prompts/NN-cover-<slug>.md; in the WeChat Official Account scenario, after generation the cover.png can be used directly as the downstream soia-pkm-publish-wechat-draft 's scripts/publish.py --article <md> --cover <output-dir>/cover.png input (soia-pkm-publish-wechat-draft is an independent downstream skill; configure it according to its own installation instructions; this skill does not modify it).
The final reply gives a completion receipt (see "Logging and Completion Receipt").

Dependencies and installation

Install this skill (single skill):

npx skills add soia-team/soia-open-skills -g -a '*' -s soia-pkm-cover-image -y

Dependency	Type	Installation / configuration	What to do when missing
codex CLI（`codex exec`）	Hard dependency (the only image generation backend in v1)	Install the codex CLI and complete login; for specific commands, refer to the current version of the official documentation	If it cannot be detected on PATH, or the login status check fails:stop generation, tell the customer what is missing and how to install/log in, and ask for the next step; do not silently switch to code rendering or other undeclared tools
`soia-pkm-publish-wechat-draft`	Downstream integration (not a dependency of this skill)	See the skill's own installation instructions	This skill is only responsible for producing `cover.png`; whether to install it and when to invoke the WeChat Official Account drafts box skill is up to the client; this skill does not install or modify it on the client's behalf

Configuration conventions:

~/.config/soia-skills/soia-open-skills/soia-pkm/soia-pkm-cover-image/config.yml
SOIA_PKM_COVER_IMAGE_CONFIG_FILE=<custom-config-path>

This skilldoes not needany account credentials, cookies, or tokens—config.yml only stores generation preferences (default type/palette/aspect, whether to skip confirmation), and does not store secret values.
COVER_IMAGE_OUTPUT_DIR can be used as a process environment variable, or written in the private config.yml 's env: mapping, to override the default value of the same directory as the draft when no user path is specified.
If the client does not want private preferences, they can choose not to create config.yml, and this skill runs with the built-in defaults (auto recommended + 2.35:1 + confirmation required).
For an example, see the config.example.yml。

Logging and completion receipts

Every execution must let the client see the entire process of judgment, confirmation, and output. Minimum receipt format:

完成：<一句话说明本次生成了什么封面，或说明因何未生成>。

日志摘要：
- 五维参数：type=<值> palette=<值> rendering=<值> text=<值> mood=<值>（各值标注"客户指定"或"AI 推荐"）
- 比例：<aspect>（默认 2.35:1，或客户/用途指定值）
- 确认记录：<确认清单的客户答复摘要，或"客户已用 --quick / 明确说直接生成，跳过确认，本次沿用的假设是：…">
- 后端：<codex-exec 或客户指定的其它后端；不可用时写"探测失败，已停止并询问客户">

产出：
- prompt 文件：<prompts/NN-cover-<slug>.md 路径>
- 封面图：<output-dir>/cover.png（或未生成时写"无，原因见上"）

文件变化：
- <本次新建/覆盖的绝对路径列表；未生成时写"未改动文件">

问题与下一步：
- <后端缺失 / 标题与原文不一致需要客户核对 / 建议公众号场景下一步把 cover.png 交给 soia-pkm-publish-wechat-draft；没有则写"无，可直接使用产出">

Artifact path (Category C user deliverable)

A user-specified output path takes priority.
When unspecified, read the process environment variable or the private config.yml 's COVER_IMAGE_OUTPUT_DIR; when neither is configured, by default place the cover and prompt inthe same directory as the draft article, so that cover.png can directly integrate with soia-pkm-publish-wechat-draft --cover. Before using the default value, the exact path of the draft article must already be obtained.
When there is neither a user-specified path,COVER_IMAGE_OUTPUT_DIR, nor a draft article path, ask the user first; do not silently choose cwd or another default directory.
It is explicitly forbidden to write to the vault root outputs/, and outputs/cover-image/<name>/ must not be created as the default location.

The internal structure remains prompts/NN-cover-<slug>.md and cover.png; if the user specifies a directory, organize these two artifacts according to that directory. Regeneration continues to use cover-v2.png and other incrementing filenames while retaining old versions.

Five-dimensional parameters (selected, not the full upstream set)

Dimension	Available values	Default	One-sentence description
type	hero / conceptual / typography / metaphor / scene / minimal	auto (determined by content)	Composition motif: hero main visual large image, conceptual abstract concept metaphor, typography large-type layout, metaphor single metaphorical symbol, scene scene illustration, minimal minimalist whitespace
palette	warm / elegant / cool / dark / vivid / mono	auto	Color tone: warm warm tones, elegant premium gray, cool cool tones, dark dark background, vivid high saturation, mono black and white
rendering	flat-vector / hand-drawn / painterly / digital	auto	Rendering texture: flat-vector flat vector, hand-drawn hand-drawn feel, painterly painterly texture, digital digital illustration
text	none / title-only / title-subtitle	title-only	Text hierarchy: none no text, title-only title only (default), title-subtitle title + subtitle
mood	subtle / balanced / bold	balanced	Emotional intensity: subtle low contrast, balanced moderate (default), bold high contrast

Aspect ratio (aspect) and publishing chain integration

aspect	Purpose	Size reference
2.35:1 (default)	WeChat Official Account header image	900×383
16:9	General horizontal / X image	—
1:1	Xiaohongshu square image	—

When this skill is not given a publishing channel, it defaults to producing images for the official account scenario (2.35:1); if the client mentions X or Xiaohongshu, switch to the corresponding aspect ratio. The produced cover.png path is designed to be directly usable as a downstream connection:

python3 scripts/publish.py --article <文章md> --cover <output-dir>/cover.png

This command belongs to soia-pkm-publish-wechat-draft 's own script; the client must first configure credentials according to that skill's installation instructions; this skill is only responsible for generating cover.png to the agreed path, and does not replace the official account draft box skill in performing publishing.

Confirmation gate (must be passed before generation)

Before generation, the client must confirm the following four items—they determine whether the image can be used directly:type, palette, text (text hierarchy), aspect (ratio). rendering and mood are also displayed together so the client can see everything at once, but the mandatory confirmation threshold is based on the first four items.

The recommended values derived from content analysis, and the preference default values inconfig.yml , all count only asrecommended input, and do not constitute a reason to skip confirmation.
The only skip condition: the client explicitly says "generate directly"/in the current sentenceexplicitly says "directly generate"/--quick/equivalent expression, or the private config.yml has set quick_mode: true。
After skipping confirmation, the completion receipt must state which assumptions were used this time (which default type/palette/aspect was used).

Backend resolution

Image generation backend resolution order (two levels; v1 has only one real backend):

Specified in the current message — the client explicitly named the backend to use in this round; use it directly.
Detect codex CLI — check whether codex is executable on PATH and has completed login (use the official read-only login status check; for the specific subcommand, refer to the current codex CLI version documentation). If satisfied, delegate generation to it: invoke it in the form codex exec , handing the contents of the saved prompt file, the target aspect ratio, and the output path to codex, and let codex's internal image_gen capability perform the actual image generation; this skill is only responsible for organizing the prompt, passing parameters, and verifying whether the artifact has landed.
- Note on landing path: images generated by codex exec land by default under the ~/.codex/generated_images/<session-id>/ cache directory, andwill notautomatically appear at the <output-dir>/cover.pngagreed by this skill. After invocation, you must go to that cache directory to locate the file just generated, then copy/move it to the agreed output path, and only then verify landing; do not check the target path only once and conclude "generation failed".
- Note on model version (lesson from actual testing 2026-07-10): codex being in PATH and logged in ≠ being able to generate images. The default model configured by the account/desktop client may be newer than the current CLI version (actual test: the default gpt-5.6-sol directly reports 400 "requires a newer version of Codex" on CLI 0.142.5). When encountering a "model not supported" type error, read ~/.codex/models_cache.json to find the model for supported_in_api=true , explicitly add -m <受支持模型>(such as -m gpt-5.5) and retry;do not misjudge this kind of failure as "backend unavailable" and take the stop branch。
None are satisfied — clearly inform the client that "codex CLI is unavailable (not installed/not logged in/detection failed, specify which one)", and ask the client whether they want to install and log in now, switch to a machine that already has it set up, or postpone generation.Never silently degradein any other undeclared way.

⛔ Two red lines (must be observed)

It is forbidden to pass off SVG / HTML / canvas / any code rendering as a bitmap. As long as what the client wants is a "cover image", the deliverable must be a genuinely generated bitmap (PNG/JPG), and you must not fob them off with an image drawn in vector code—even if the content looks "like an image". When the image generation backend is unavailable, follow the "none of the above are satisfied" branch above and ask the client; you must not settle for less by switching to code rendering.
It is forbidden to trace characters, alter characters, or patch on an already generated bitmap. If the text is wrong, blurry, or the layout is cramped, the only legitimate fix ischange the prompt and regenerate, and you must not use Pillow/Canvas/ImageMagick/OCR overlaying or any other programming means to directly alter pixel-level text on the original image. When regenerating, write a new prompt file and a new output file name,keep the old versionfor the client to compare, without overwriting the old artifact.

Prompt persistence (hard requirement)

Every time the image generation backend is calledbefore, you must write the complete final prompt used for this generation into the artifact directory under prompts/NN-cover-<slug>.md（NN starts from 01 and increments,slug is a 2–4 English word kebab-case phrase, derived from the article topic). This file is a reproducible record: rerunning with a different backend and tracing afterward why it was generated this way both rely on it, not on memory. When regenerating to fix text errors, open a new prompt file with a higher number, without overwriting the old one.

Composition principles

Leave 40–60% whitespace: do not cram the subject to fill the frame; leave breathing room for the title text.
Main element centered or offset to the left: place the visual focus in the center or slightly left of the frame, leaving the right side/bottom for text layout.
Use only simplified silhouettes for people; realistic faces are forbidden: any human element must be drawn as a simplified silhouette or abstract form; do not generate a recognizable realistic face.
The title must use the exact title provided by the client or from the source text; fabrication or rewriting is forbidden：text is not none , the title text appearing in the image must correspond word for word to the title given by the client; when unsure of the client's exact wording, ask first, and do not "optimize the wording" on the client's behalf.

Output directory structure

<draft-article-dir>/
├── prompts/
│   └── 01-cover-<topic-slug>.md
└── cover.png

<topic-slug> and prompts/ inside slug stay consistent, for easy corresponding lookup.
When the client specifies another output directory, the client's specification prevails, but the internal structure of "prompts/ subdirectory + cover.png" must still be observed.
Text error correction regeneration: the new version uses cover-v2.png(incrementing in order) + a correspondingly higher-numbered prompt file; the old version is not deleted until the client confirms it can be cleaned up.

Boundaries and limitations

This skill does not generate illustrations, multi-image long images, or in-article supporting images—those belong to other transformation artifacts (such as soia-pkm-transform covered infographics/long images); this skill only makes a single cover.
This skill does not handle publishing and does not touch any account credentials or platform APIs; handing cover.png to a downstream publishing skill means the subsequent actions are completed by the client or the corresponding skill itself.
This skill does not guarantee that the image generation backend will always produce a satisfactory result—image generation involves some uncertainty; when the result is unsatisfactory, follow the "regenerate" process; it does not mean this skill itself failed.

Roadmap v2

Illustrations within the article (article illustration, multiple illustrations within the body text rather than a single cover image) are left for a later version; this version only covers single cover image generation.