richtabor/agent-skills/markdown-img-alt-text

Alt Text for Markdown Images

Scan markdown files for image embeds that are missing alt text and add detailed, descriptive alt text by reading each image.

Supported Formats

• Obsidian wiki-style: ![[image.png]] → ![[image.png|alt text here]]
• Standard markdown: ![](path/to/image.png) → ![alt text here](path/to/image.png)

Detect which format the file uses and apply alt text accordingly.

When to Use

• User asks to add or update alt text on images
• User asks to describe images in their notes
• User asks to make images accessible or searchable

Process

1. Find Images Missing Alt Text

Search the target scope (a specific note, folder, or the whole project) for image embeds without alt text:

• Obsidian: ![[filename.ext]] with no | pipe character (image extensions: png, jpg, jpeg, gif, svg, webp)
• Standard markdown: ![](path) where the alt text between [] is empty

Images that already have alt text — ![[image.png|description]] or ![description](path) — should be skipped.

2. Read Each Image

For each image found, use the Read tool to view the image file. Resolve the image path based on the project structure (e.g., an attachments folder, a public/images directory, or a relative path).

3. Write Detailed Alt Text

Write thorough, detailed alt text for each image. The alt text should:

• Describe the full visual content — what is shown, what text is visible, what the layout looks like
• Capture specific details like button labels, heading text, color choices, UI patterns, data values
• Be written as a single continuous description (no line breaks) since it goes inline in the embed
• Be detailed enough that someone reading only the alt text would understand the image without seeing it
• Avoid starting with "Image of" or "Screenshot of" — just describe what's there directly

4. Update the Embeds

Use the Edit tool to add alt text in the correct format for the embed style used in that file.

Scope

• If the user specifies a file or folder, only process that scope
• If no scope is given, ask the user whether to process a specific file, folder, or the whole project
• Report how many images were found, how many already had alt text, and how many were updated

Examples

Obsidian — before:

![[dashboard-screenshot.png]]

Obsidian — after:

![[dashboard-screenshot.png|Analytics dashboard showing a bar chart of monthly revenue from January to June 2026, with a sidebar navigation listing Overview, Reports, and Settings. The header reads "Q2 Performance" in bold with a blue export button in the top right.]]

Standard markdown — before:

![](images/dashboard-screenshot.png)

Standard markdown — after:

![Analytics dashboard showing a bar chart of monthly revenue from January to June 2026, with a sidebar navigation listing Overview, Reports, and Settings.](images/dashboard-screenshot.png)