playbooks

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

markdown-img-alt-text skill

/skills/markdown-img-alt-text

This skill adds thorough alt text to markdown images by analyzing content and updating Obsidian or standard markdown embeds.

npx playbooks add skill richtabor/agent-skills --skill markdown-img-alt-text

Review the files below or copy the command above to add this skill to your agents.

Files (1)
skill.md
3.3 KB
---
name: markdown-img-alt-text
description: Adds detailed alt text to markdown image embeds that are missing it. Supports both Obsidian wiki-style (![[image]]) and standard markdown (![](path)) formats. Reads each image, describes its content thoroughly, and updates the embed inline. Triggers on "add alt text", "update alt text", "describe images", "missing alt text", or "image descriptions".
---

# 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)
```

Overview

This skill scans markdown files and adds detailed alt text to image embeds that are missing it. It supports both Obsidian wiki-style embeds (![[image]]) and standard markdown (![](path)). The skill reads each image, generates a single-line, descriptive alt text that captures visual and textual details, and updates the embed inline. It reports counts of found images, skipped items, and updates applied.

How this skill works

The skill searches the specified scope (file, folder, or project) for image embeds that lack alt text: Obsidian embeds without a pipe (|) and standard markdown with empty square brackets. For each found image it resolves the path, reads the image file using the Read tool, and writes a single continuous descriptive alt text that covers visible text, layout, colors, and relevant details. Finally it updates the markdown using the Edit tool in the same embed format the file uses and summarizes the results.

When to use it

  • When you ask to add or update alt text for images across notes or a repo
  • When you want your documentation or notes to be accessible to screen readers
  • When you need searchable, descriptive image metadata for indexing
  • When preparing content for publication or sharing with people who rely on descriptions
  • When converting quick image-heavy notes into production-ready documentation

Best practices

  • Run the skill on a single file or folder first to verify descriptions before bulk changes
  • Provide the scope explicitly (file, folder, or whole project) to avoid unintended edits
  • Prefer concise but specific descriptions: include visible text, key colors, layout, and data values
  • Keep alt text as one continuous sentence per embed and avoid phrases like "Image of" or "Screenshot of"
  • Skip images meant to be purely decorative by marking them manually or leaving them out of the scope

Example use cases

  • Add descriptive alt text across an Obsidian vault so notes become accessible to screen readers
  • Update a docs folder of markdown files with descriptive captions for product screenshots
  • Describe diagrams and charts in a research notebook so collaborators can understand results without images
  • Prepare a blog repository for publishing by ensuring all images include meaningful alt text
  • Generate searchable image descriptions to improve internal knowledge base discoverability

FAQ

Which embed formats are supported?

Both Obsidian wiki-style embeds (![[image.png]]) and standard markdown images (![alt](path) or ![](path)).

Will it overwrite existing alt text?

No — images that already include alt text in either format are skipped by default; you can request updates explicitly.

How does the skill handle image paths?

It resolves relative and common project paths (attachments, images folders, public/images) to open the image file before generating descriptions.

What kind of descriptions are generated?

Single-line, detailed descriptions that cover visible text, layout, color cues, UI elements, and data values so someone can understand the image without seeing it.