docs-media — Media Analysis

Before Starting#

1. Get the repository. Ask for the GitHub repo URL or {user}/{repo}.
2. Check Docsbook. Run mcp__docsbook__list_workspaces to find the workspace.
   • If found → use mcp__docsbook__get_doc_graph and mcp__docsbook__read_doc_sections to scan image references in markdown.
   • If not found → offer to add it first.
3. Check the graph. If get_doc_graph returns an empty graph or no data → run mcp__docsbook__reindex_doc_graph to generate it, then retry. If it returns a stale warning, offer to reindex before proceeding.
4. Two levels of analysis. From Docsbook MCP, detect issues visible in markdown (missing alt, generic filenames in links, missing captions). Physical file checks (size, age) require local repo access — note which checks need it.
5. Skip if no media. If read_doc_sections finds no image or video references, skip this skill.

Core Principles#

1. Text is primary, media amplifies#

Images, videos, and diagrams should strengthen the text — not replace it. A page that is 80% screenshots is an anti-pattern.

2. Stability over beauty#

UI changes. Full-page screenshots go stale fastest. For frequently-changing UI, a text description ages better than a screenshot.

3. Lightweight by default#

Large media files slow page load and hurt SEO. PNG screenshots under 500 KB, GIF under 2 MB.

4. Diagrams as code#

A Mermaid diagram in markdown versions with the code, renders automatically, and updates in a PR. A static PNG requires a designer and goes stale silently.

Checklist#

File Formats#

• PNG for UI screenshots — not JPG (JPG degrades text rendering)
• GIF only for short animations — ≤ 5 seconds, ≤ 2 MB
• No video files committed to the repo — use YouTube, Loom, or Vimeo embeds
• Mermaid preferred over static PNG for diagrams and flowcharts

File Size (local repo check)#

• PNG screenshot < 500 KB
• GIF < 2 MB
• Total media per page < 5 MB
• No MP4/MOV files committed to repo

# Find large media files
find . -type f \( -name '*.png' -o -name '*.jpg' -o -name '*.gif' -o -name '*.mp4' \) -size +500k -exec ls -lh {} \;

File Names (detectable from markdown links)#

• kebab-case — workspace-settings-api-keys.png
• Descriptive — name describes content, not position: not screenshot1.png, image.png, Screenshot 2024-01-15.png
• No spaces or special characters in file names
• No timestamps in file name — content description, not capture date
• Prefix by type optionally — ui-, diagram-, icon-

Alt Text (detectable from markdown)#

• All informative images have alt — ![alt](image.png) not ![](image.png)
• Decorative images have empty alt — ![](decoration.png)
• Alt describes content — "Workspace settings with API key field" not "Screenshot"
• Alt is not "image of" / "screenshot of" — screen reader already announces it
• Length ≤ 125 characters — longer descriptions go in the body

UI Screenshots#

• Cropped to the relevant area — not the full browser window with chrome
• No personal data — use test accounts, placeholder names/emails
• No timestamps visible on the screenshot itself (they go stale)
• Important area is highlighted — box, arrow, or highlight overlay
• Consistent theme — all screenshots in light mode OR all in dark mode

Screenshot Freshness (local repo check)#

Screenshots older than 180 days in an actively developed product are very likely stale:

# Screenshots older than 180 days
find . -name '*.png' -mtime +180 -exec ls -lh {} \;

From Docsbook MCP: check last_updated of pages containing screenshots — if a page hasn't been updated in 180+ days and contains screenshots, flag for manual review.

Videos#

• Captions/subtitles on all videos
• Transcript or summary in the page text
• Not auto-play
• Described in text before the embed — what the video shows, how long it is
• Hosted externally — YouTube, Loom, Vimeo — not committed as a file

Diagrams#

• Mermaid in markdown for flowcharts, architecture, ER diagrams:

  ```mermaid
  graph LR
    GitHub --> Docsbook
    Docsbook --> CDN
    CDN --> Users
  ```
  

• Source file saved alongside PNG export — .excalidraw, .drawio — so diagrams can be updated
• Text alternative for complex diagrams that can't be Mermaid
• Readable in both light and dark mode

What to Look For#

Output Format#

{
  "file": "docs/quick-start.md",
  "line": 34,
  "severity": "critical",
  "rule": "image-missing-alt",
  "found": "Line 34: ![](screenshots/setup.png) — informative image with no alt text.",
  "suggestion": "Add descriptive alt: '![Docsbook workspace creation form with GitHub repo URL field](screenshots/setup.png)'"
}

{
  "file": "docs/guides/api-setup.md",
  "line": 67,
  "severity": "high",
  "rule": "generic-filename",
  "found": "Line 67: ![Settings panel](screenshots/screenshot1.png) — filename 'screenshot1.png' is not descriptive and will be impossible to identify when the folder has many screenshots.",
  "suggestion": "Rename to a descriptive kebab-case name: 'screenshots/api-settings-key-field.png'. Update the link in the markdown."
}

{
  "file": "docs/architecture.md",
  "line": 12,
  "severity": "medium",
  "rule": "diagram-could-be-mermaid",
  "found": "Line 12: ![System architecture](architecture.png) — static PNG diagram. Hard to keep updated without design tools.",
  "suggestion": "Convert to Mermaid:\n```mermaid\ngraph LR\n  GitHub --> Docsbook\n  Docsbook --> CDN\n  CDN --> Users\n```\nMermaid renders automatically, versions in git, and updates in a PR without design software."
}

Task-Specific Questions#

When invoked directly, ask:

1. Is local repo access available? File size and age checks require it.
2. What's the screenshot freshness threshold? Default is 180 days.
3. Convert PNG diagrams to Mermaid? Or just report them?

Tool Integrations#

Related Skills#

• docs-accessibility — alt text is an a11y requirement
• docs-maintenance — stale screenshots are a maintenance issue
• docs-seo — descriptive filenames and alt text help SEO
• docs-analyze — orchestrator