| name | image-caption-writing |
| description | Guidance for writing, rewriting, or removing image captions using the RHI-094 cleanup standards. Use when reviewing img-caption shortcode content, figure captions, and nearby post-figure paragraphs for redundancy and reader value. |
| argument-hint | Provide article routes, caption candidates, or img-caption snippets to review. |
| user-invocable | true |
| license | Forward Proprietary |
| compatibility | Hugo content in src/content/posts/** and img-caption shortcode workflows |
Image Caption Writing
Use this skill to decide whether an image should keep a visible caption, rewrite it, or remove it. The goal is reader value: captions should add unique image-specific meaning, not repeat surrounding copy.
When to Use This Skill
- Reviewing or writing
caption="..." text for {{< img-caption >}} shortcodes
- Cleaning caption text that may duplicate nearby body copy
- Auditing first plain paragraphs after figures for leftover caption-style text
- Creating quality checks for caption consistency in content review
- Not for: image conversion mechanics, shortcode rendering bugs, Hugo template styling changes, or always-on repository coding standards
Quick Start
- Evaluate the candidate caption against alt text plus the nearest heading, paragraph, or list item.
- Classify the caption as
keep, rewrite, or remove using the core decision rule.
- Review the first plain post-figure paragraph independently.
- Record a one-line reason describing net-new reader value or redundancy.
- If uncertain, prefer
remove unless a concrete image-specific benefit is evident.
Core Decision Rule
Evaluate each image in this order:
- Compare the caption candidate against nearby heading and nearest explanatory paragraph/list item.
- Remove the caption if nearby copy already communicates the same reader-facing message.
- Rewrite the caption if a short image-specific label is still useful for scanability or disambiguation.
- Keep the caption only when it adds net-new visible value not present in alt text or nearby copy.
Good and Bad Caption Rules
Good caption traits
- Names a specific UI element, warning, state, or comparison axis shown in the image
- Adds concise context that helps readers identify or reference the image quickly
- Is short and purposeful (usually one phrase or a short sentence)
- Distinguishes this image from adjacent screenshots in the same section
Bad caption traits
- Duplicates alt text with the same meaning
- Restates the section heading or nearby paragraph without adding new value
- Uses low-value labels only (
Figure X, raw URL, generic screenshot label)
- Repeats a post-figure paragraph that already explains the same point
Post-Figure Paragraph Rule
After deciding caption disposition, evaluate the first plain paragraph immediately after the figure.
Remove that paragraph when all are true:
- It directly follows the figure with no structural break
- It acts only as a figure label or short restatement
- It duplicates the figure message or nearby copy
- Removing it does not break narrative flow
Keep that paragraph when any are true:
- It adds new instruction, warning, interpretation, or next-step context
- Later sentences depend on it
- It starts the next argument instead of labeling the figure
Audit-Learned Edge Cases
- Keep a figure-number style caption only when body copy explicitly references that figure number.
- Remove raw URL captions unless the URL itself is the subject being explained.
- For image sequences, keep short differentiating captions rather than repeating generic labels.
- Preserve reviewed keep-body exceptions when the paragraph is clearly instructional or transitional prose.
- If adjacent prose and caption compete, keep the stronger prose and remove the weaker caption.
Quick Rubric
| Condition | Action |
|---|
| Caption is empty after trimming/placeholder cleanup | Remove caption |
| Caption duplicates alt text meaning | Remove caption |
| Caption duplicates nearby copy meaning | Remove caption |
| Topic overlaps nearby copy but image needs a specific label | Rewrite caption |
| Caption adds unique, image-specific reader value | Keep caption |
See the full rubric and examples in Caption Rubric.
Examples
Example: remove
- Section heading:
Setting up inventory lists
- Nearby paragraph: explains that the screenshot shows inventory list setup
- Caption candidate:
Setting up inventory lists
- Decision: remove (no new reader value)
Example: rewrite
- Nearby paragraph: explains inventory synchronization generally
- Caption candidate:
Inventory synchronization settings
- Improved caption:
Omnichannel Inventory toggle state before activation
- Decision: rewrite (adds image-specific identifier)
Example: keep
- Nearby paragraph: discusses API error handling generally
- Caption:
HTTP client warning banner: stale cache detected
- Decision: keep (specific visual state not stated nearby)
Verification Checklist
References
