Article Figure Spot

Finds all positions in an article that benefit from a figure, then either outputs the article with inline prompt placeholders (author generates and inserts images later) or generates all figures in one run using the built-in image script and saves them so the author can insert image links.

Input

Article content can be provided in either way:

• File path: User sends a path to a Markdown file (e.g. /article-figure-spot path/to/article.md).
• Pasted text: User writes in the chat that they want figures for an article and pastes the full text below (e.g. “用这个 Skill 给如下文章配图：” then the article). Treat the pasted block as the source article; if needed, save it to a temp or project file for structure analysis, then proceed with the workflow.

When only pasted text is given, infer options from context or ask once for --prompts-only vs --generate and density if ambiguous.

Script directory

Scripts live in the scripts/ subdirectory of this skill.

• SKILL_DIR = directory containing this SKILL.md (the skill root).
• Script path = ${SKILL_DIR}/scripts/generate-image.mjs

Script	Purpose
scripts/generate-image.mjs	Calls OpenAI image API; reads prompt from file(s), writes image to given path. Runs with Node (no Bun).

Invocation (generate mode, one figure):

node ${SKILL_DIR}/scripts/generate-image.mjs --promptfiles prompts/NN-type-slug.md --image figure-spot/{topic-slug}/NN-type-slug.png --ar 16:9

Environment: The script needs OPENAI_API_KEY. It loads .env from the current working directory and from the skill directory (SKILL_DIR). Optional: OPENAI_BASE_URL, OPENAI_IMAGE_MODEL (default in script).

Modes

Mode	Invocation	Result
Prompts only	--prompts-only or default when no image-gen available	Article with inline prompt blocks at each spot; author runs image gen per prompt and inserts.
Generate all	--generate	Prompts written to files, image-generation command run for each; images saved; article emitted with image paths ready to paste.

Usage

# Prompts only: output article with inline figure prompts (no image gen)
/article-figure-spot path/to/article.md
/article-figure-spot path/to/article.md --prompts-only

# Generate all: spot positions, create prompts, run image gen, save images
/article-figure-spot path/to/article.md --generate

# Optional: control density and output dir
/article-figure-spot article.md --generate --density rich --out-dir figures

Options

Option	Description
--prompts-only	Only insert prompt placeholders; do not run image generation.
--generate	Run image generation for every spotted position and save images.
--density <level>	sparse (2–3 figures), medium (4–6), rich (7+). Default: medium.
--out-dir <dir>	Root directory for prompt files and generated images. Default: figure-spot/{topic-slug}/.
--lang <code>	Language for prompts and alt text (e.g. en, zh). Default: detect from article.

Workflow

Copy and track:

Figure Spot Progress:
- [ ] Step 1: Load article and analyze structure
- [ ] Step 2: Identify figure positions → placement list
- [ ] Step 3: Confirm positions with user (optional but recommended)
- [ ] Step 4a (prompts-only): Write output article with inline prompts
- [ ] Step 4b (generate): Create prompt files → run image gen → save images → write output article with image refs
- [ ] Step 5: Summary and insert instructions

Step 1: Load and analyze

• Obtain article: From the given file path (read file) or from the user’s message (pasted text). If only pasted text: optionally save to e.g. figure-spot/{topic-slug}/source.md for reference.
• Read the full article content.
• Detect language; note sections and paragraph boundaries.
• Infer topic and audience.

Step 2: Identify figure positions

Use rules in references/position-rules.md:

• Where a figure adds clarity: concepts, processes, comparisons, data, timelines, frameworks.
• Do not add figures for: purely decorative spots, literal illustrations of metaphors, or redundant-to-text content.

For each position record:

• Anchor: Which paragraph or section (quote or heading).
• Role: e.g. concept, process, comparison, timeline.
• Prompt idea: One-sentence description of what the image should show.

Respect --density: sparse 2–3, medium 4–6, rich 7+ figures.

Step 3: Confirm (recommended)

Present the placement list:

• Index, anchor snippet, role, suggested filename.
• Ask user to confirm or trim/add positions before continuing.

Step 4a: Prompts-only output

• Produce an output article (new file or clearly marked block) that matches the original but at each chosen spot inserts an inline block like:

<!-- FIGURE N: [anchor description] -->
<!-- PROMPT: [full image-generation prompt in 1–3 sentences] -->
<!-- FILE: NN-{type}-{slug}.png -->
<!-- END FIGURE -->

• Author uses the PROMPT and FILE lines to run their image-generation tool and then replace the block with ![alt](path/NN-{type}-{slug}.png).

Prompt content should follow references/prompt-guide.md (concise, scene/layout, aspect ratio).

Step 4b: Generate-all output

1. Create output directory (e.g. figure-spot/{topic-slug}/ or --out-dir).
2. For each position:

   • Write a prompt file, e.g. prompts/NN-{type}-{slug}.md, with the full image-generation prompt (see references/prompt-guide.md).

   • Run this skill’s image script from the project root (or cwd) so that relative paths for prompts and output resolve correctly:

     node ${SKILL_DIR}/scripts/generate-image.mjs --promptfiles <path-to-prompt.md> --image <path-to-output.png> --ar 16:9

     Use the same aspect ratio for all article figures (e.g. 16:9) unless the user asks otherwise.

   • The script writes the image to the given path. On failure: retry once; then log and continue.

3. Produce the output article with each figure block replaced by a real image reference, e.g. ![alt text](figure-spot/{topic-slug}/NN-{type}-{slug}.png).
4. Naming convention: see references/output-layout.md.

Image generation is built-in: The skill uses its own scripts/generate-image.mjs, which calls the OpenAI image API (run with Node). The user must set OPENAI_API_KEY (in .env next to the skill or in the current directory) for --generate to work.

Step 5: Summary（必须包含「图 ↔ 文中位置」闭环）

结束时必须向用户提供插图与文中插入位置对照，让用户明确「哪张图插在文章哪里」：

• 插图 ↔ 文中位置对照表（必给）：每一行说明「图片路径 / 文件名」与「文中插入位置」。
  • 插入位置写清：在哪个标题/段落之后，例如：「在标题 ## 复盘的三个层次 之后」「在段首为『推荐流程（四步）』的段落之后」。
  • 格式示例：

图片文件	文中插入位置
01-concept-three-layers.png	在 ## 复盘的三个层次 这一节段落后
02-process-four-steps.png	在段首为「推荐流程（四步）」的段落之后

• 同时可列出：对应 prompt 文件、图片路径（out-dir 下的相对路径或绝对路径）。
• Prompts-only：列出上述对照表 + 提醒作者按 PROMPT 生图后，用该表把每张图插到对应位置。
• Generate-all：列出上述对照表 + 生成图片的路径 + 已插入图片的 article-with-figures.md 路径。

Output layout

Default layout under figure-spot/{topic-slug}/:

figure-spot/{topic-slug}/
├── source.md          # Copy of or link to source article
├── placement.md       # Table: index, anchor, role, prompt summary, filename
├── prompts/
│   ├── 01-concept-xxx.md
│   └── 02-process-yyy.md
├── 01-concept-xxx.png
├── 02-process-yyy.png
└── article-with-figures.md   # (generate mode) article with image refs inserted

Slug: 2–4 words from article topic, kebab-case. If directory exists, append timestamp.

Prompt rules (summary)

• One clear subject per image; state composition and layout.
• Prefer conceptual or structural descriptions over decorative or metaphorical.
• Include aspect ratio (e.g. 16:9) and, if relevant, style (e.g. diagram, scene).
• Avoid vague phrasing; avoid illustrating metaphors literally.

Details: references/prompt-guide.md.

References

File	Content
references/position-rules.md	What to illustrate and what to skip.
references/prompt-guide.md	How to write each figure prompt.
references/output-layout.md	Dir structure and file naming.

Notes

• Generate mode uses this skill’s own scripts/generate-image.mjs (OpenAI image API, run with Node). Set OPENAI_API_KEY in .env in the skill directory or cwd.
• For sensitive or copyrighted subjects, prompt for a stylized or non-literal treatment.
• Keep article language and prompt/alt language consistent.