markdown-img-alt-text_skill

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 (). 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