Media content 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-media-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 explicitly said "generate directly"/ inthe current sentencealready explicitly stated "directly generate"/
--quick。 - Backend resolution (see the "Backend resolution" section): if the current message specifies a backend, use it; otherwise probe 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 thecover.pngcan be used directly as the downstreamsoia-media-publish-wechat-draft'sscripts/publish.py --article <md> --cover <output-dir>/cover.pnginput (soia-media-publish-wechat-draftis 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 "Logs and completion receipt").
Dependencies and installation
Install this skill (single skill):
npx skills add soia-team/soia-open-media-content-skills -g -a '*' -s soia-media-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-media-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 skill is decided by the client; this skill does not install or modify it on their behalf |
Configuration conventions:
~/.config/soia-skills/soia-media-cover-image/config.yml
SOIA_MEDIA_COVER_IMAGE_CONFIG_FILE=<custom-config-path>
- this skilldoes not needany account credentials, cookies, or tokens——
config.ymlonly stores generation preferences (default type/palette/aspect, whether to skip confirmation), and does not hold secret values. COVER_IMAGE_OUTPUT_DIRcan be used as a process environment variable, or written in the privateconfig.yml'senv: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 skip creating
config.yml, and this skill runs with the built-in defaults (autorecommended + 2.35:1 + confirmation required). - For examples, see the
config.example.yml。
Logging and completion receipt
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-media-publish-wechat-draft；没有则写"无，可直接使用产出">
Artifact path (Category C user deliverable)
- A user-specified output path takes priority.
- If unspecified, read the process environment variable or the private
config.yml'sCOVER_IMAGE_OUTPUT_DIR; if neither is configured, by default place the cover and prompt inthe same directory as the draft article, so thatcover.pngcan directly connect tosoia-media-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. - Explicitly prohibited from writing to the vault root
outputs/, and must not createoutputs/cover-image/<name>/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 under that directory. Regeneration continues to use cover-v2.png and other incrementing filenames while retaining old versions.
Five-dimensional parameters (curated, not the full upstream set)
| Dimension | Available values | Default | One-sentence description |
|---|---|---|---|
| type | hero / conceptual / typography / metaphor / scene / minimal | auto (judged 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 elegant 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 does not specify a publishing channel, it generates images for the WeChat Official Account scenario by default (2.35:1); if the customer 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-media-publish-wechat-draft 's own script; the customer 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 WeChat Official Account draft box skill in performing publishing.
Confirmation gate (must be passed before generation)
Before generation, the customer must confirm the following four items — they determine whether the image can be used directly:type, palette, text (text hierarchy), aspect (aspect ratio). rendering and mood are displayed together so the customer 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 in
config.yml, both count only asrecommended input, and do not constitute a reason to skip confirmation. - The only skip condition: the customer inthis current sentenceexplicitly says "generate directly"/
--quick/equivalent expression, or the privateconfig.ymlhas setquick_mode: true。 - skip confirmation, then the completion receipt must state which assumptions were carried over 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 by the current message — the customer explicitly named the backend to use in this round, use it directly.
- Detect codex CLI — check whether
codexis executable onPATH, and whether login has been completed (using the official read-only login status check; the specific subcommand is subject to the current codex CLI version documentation). If satisfied, delegate generation to it: invoke it in the form ofcodex exec, handing over the saved prompt file content, target aspect ratio, and output path to codex together, and codex's internal image_gen capability performs the actual image generation; this skill is only responsible for organizing the prompt, passing parameters, and verifying whether the artifact is written to disk.- Output path note: images generated by codex exec land by default in the
~/.codex/generated_images/<session-id>/cache directory, andwill notautomatically appear in this skill's agreed<output-dir>/cover.png. After invoking, you must go to that cache directory to locate the just-generated file, then copy/move it to the agreed output path, and only then verify that it is written to disk; do not check the target path only once and conclude "generation failed". - Model version note (lesson learned in practice 2026-07-10): codex being on PATH and logged in ≠ able to generate images. The default model configured on the account/desktop may be newer than the current CLI version (observed: the default
gpt-5.6-solon CLI 0.142.5 directly reports 400 "requires a newer version of Codex"). When encountering a "model not supported" type error, read~/.codex/models_cache.jsonto findsupported_in_api=truemodels, explicitly add-m <受支持模型>(e.g.-m gpt-5.5) and retry;do not misjudge this kind of failure as "backend unavailable" and take the stop branch。
- Output path note: images generated by codex exec land by default in the
- none are satisfied — explicitly inform the customer "codex CLI is unavailable (not installed/not logged in/detection failed, specify which one)", and ask the customer whether they want to install and log in now, switch to a machine that already has it set up, or postpone generation.Never silently downgradein any other undeclared way.
⛔ Two red lines (must be followed)
- 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); you may not fool them by drawing an image with 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 and ask the client; you must not settle for the next best thing and switch to code rendering.
- It is forbidden to trace text, alter text, or paste patches onto an already generated bitmap. If the text is wrong, blurry, or the layout is cramped, the only legitimate fix is tochange the prompt and regenerate, and you must not use Pillow/Canvas/ImageMagick/OCR overlay or any other programming means to directly modify pixel-level text on the original image. When regenerating, write a new prompt file and a new output filename,keep the old versionfor the client to compare, and do not overwrite the old artifact.
Prompt persistence (hard requirement)
Before each call to the image generation backendbefore, you must write the complete final prompt used for this generation into the artifact directory under prompts/NN-cover-<slug>.md（NN increments from 01 ,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 this generation was done this way, both rely on it, not on memory. When regenerating for text correction, open a new prompt file with a higher number; do not overwrite the old one.
Composition principles
- Leave 40–60% whitespace: do not cram the subject into the whole frame; leave breathing room for the title text.
- Main element centered or offset to the left: place the visual focus in the center or toward the 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 recognizable realistic faces.
- The title must use the exact title provided by the client or from the original text; fabricating or rewriting it is forbidden：
textis notnone, 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>andprompts/inslugstay consistent, for easy corresponding lookup.- When the client specifies a different output directory, the client's specification prevails, except that the internal structure of "
prompts/subdirectory +cover.png" is still followed. - Text 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 images—these belong to other transformation artifacts (such as
soia-pkm-transformcovered infographics/long images); this skill only makes a single cover. - This skill does not publish and does not touch any account credentials or platform APIs; handing
cover.pngto a downstream publishing skill, 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 has a certain degree of uncertainty; when the result is not ideal, follow the "regenerate" process; this does not mean the skill itself failed.
Roadmap v2
Article illustrations (multiple in-text illustrations rather than a single cover image) are deferred to a later version; this version only covers single cover image generation.