soia-pkm-transform-article-visual

soia-pkm-transform-article-visual

Convert archived or specified articles into visual artifacts: long images, infographics, posters, covers, or illustrations.

Client-readable description

What this skill can do

Render Markdown / vault articles or URLs into image artifacts:

• Long image: the full article content expanded vertically into a single PNG/JPEG
• Infographic: visualization of core concepts, nodes + connections + annotations
• Term map / roadmap: cognitive path on the left + visual metaphor on the right + conclusion at the bottom
• Poster / cover: a single design draft, strong typography and visual emphasis
• Illustration / cover image: optional Codex imagegen to generate accompanying images

Client wants	Skill will do	Client can see
Generate a long image	HTML/CSS render and screenshot, prompt persisted to disk for re-runs	Image path, pixel dimensions, preview
Specify a provider	Follow the corresponding provider flow	Provider logs
Execution complete	Acceptance: file exists, dimensions are reasonable, Chinese text is readable	Completion receipt

How clients use it

1. Specify the source (URL / vault path / local Markdown) and the target visual type (long image/infographic/poster/cover, optional).
2. Optional: specify provider (local / open-design / codex-image), style, dimensions.
3. For URL sources, clip and archive first, then convert.

Dependencies and installation

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-pkm-vault@soia

When you only need this one skill, you can use the npx route. Note that the skill will land in the shared source of truth ~/.agents/skills; if a plugin is also installed, the same skill will appear with two indexes and each will drift, so it is recommended to choose one of the two:

npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-transform-article-visual -y

• Local screenshot approach: prefer the current agent's browser screenshot capability; for command-line smoke testing, Playwright can be injected, and when Playwright is missing, a system browser/PDF-image tool fallback can also be used.
• Open Design (optional enhanced dependency): only after installing soia-dev-open-design-ops can you use provider=open-design; see references/provider-open-design.md
• Codex image / imagegen (optional): see references/prompt-codex-image.md

Path	Dependency	Behavior when missing
local	None	Usable with zero dependencies
codex-image	The image generation capability of the current environment	Only this provider stops at the tool availability gate
open-design	soia-dev-open-design-ops(this path has a hard dependency) and its Open Design environment	Stop this provider, provide installation and environment check commands; do not pass it off as an Open Design result

soia-dev-open-design-ops is marked in this skill's frontmatter as optional, because the local and codex-image paths do not depend on it; once the user chooses provider=open-design, it is a hard dependency for that execution.

Private configuration goes in ~/.config/soia-skills/soia-pkm-transform-article-visual/config.yml, and can be overridden with SOIA_PKM_TRANSFORM_ARTICLE_VISUAL_CONFIG_FILE .

WorkBuddy The loading unit fornpx skills add -a '*' cannot cover it; it needs to be installed separately, see docs/install/workbuddy.md。

Logs and completion receipt

完成：<一句话>。

日志摘要：
- source: <路径或 URL>
- visual_type: long_image | infographic | poster | cover | illustration
- provider: local | open-design | codex-image
- content_mode: visual_dense
- prompt: <落盘路径>
- output: <图片路径>
- dimensions: <宽x高 px>

验证：
- 文件存在，大小 > 50KB
- 尺寸合理（宽 ≥ 750px，高视类型而定）
- 目视中文可读、无截断、无方块乱码

问题与下一步：
- <无 / provider 降级原因 / 建议>

Boundaries

• Default visual_dense mode: core concepts are retained, layout is compressed, and the original text is not repeated paragraph by paragraph.
• Text errors in bitmaps (garbled text, overflow, overlap)The only valid fix is to change the prompt and regenerate, overlaying rendered text with PIL/Canvas/ImageMagick is prohibited.
• The prompt must be written to disk at outputs/transform/<YYYY>/<stem>/prompts/ to ensure it can be rerun.
• Open Design / Codex-image are optional providers. When no provider is specified, a local path may be chosen; when the user explicitly selects open-design but its atomic layer or environment is missing, stop that provider and explain the gap; do not silently downgrade or claim that Open Design was used.
• Do not summarize the content; however, information architecture restructuring is allowed (for example, distilling paragraphs into a node relationship diagram).

Workflow

1. Confirm the source → for URLs, clip first.
2. Determine visual_type：long_image(default) / infographic / concept_map / poster / cover / illustration。
3. Select provider: user-specified > configuration > local HTML/CSS screenshot.
4. Read references/prompt-infographic.md or references/prompt-codex-image.md(for covers/illustrations) to generate the prompt and write it to disk. When the user provides a reference image, first extract its layout grammar; do not directly copy its content.
5. Generate the output to outputs/transform/<YYYY>/<stem>/。
6. First run the mechanical quality gate, then actually render the PNG; finally use view_image or an equivalent visual check to confirm that the Chinese text is readable, with no overlap and no truncation.
7. Any fallback must state the real provider in the manifest and the receipt; do not write a browser-tool fallback as Open Design or imagegen.
8. Receipt.

See references/prompt-infographic.md、references/design-prompts.md、references/quality-gates.md、references/provider-open-design.md. For Open Design's environment, daemon, directories, and atomic export operations, use soia-dev-open-design-ops/SKILL.md as the single source of truth.