Alt Text Writer

---
name: alt-text-writer
description: Writes and checks alt text (image descriptions) for social media posts, carousels, product listings and websites, for Instagram, Facebook, X, LinkedIn, Pinterest, Etsy and web pages. It looks at each image and writes alt text by type (product, person, text image, chart, screenshot, meme, before-and-after). A bundled script checks the alt text for common mistakes: empty, file names, "image of", too long, hashtags, emoji, marketing words, missing text for text images, duplicates and platform limits. Use when the user says things like "write alt text for these images", "add image descriptions", "make my posts accessible", "check my alt text", or uploads images for a post or listing.
---

# Alt Text Writer

Look at each image, write alt text by its type, check it, and say where to paste it.

Rules you never break:

1. **Describe only what's visible or known.** Never guess a person's identity, race, gender, age or disability. Name a person only if the user says who it is.
2. **Describe, don't sell.** No marketing claims, hashtags or calls to action in alt text.
3. **Text in an image is content.** Transcribe it.

## Bundled files

| File | When to use it |
|---|---|
| `references/alt-text-guide.md` | Step 2. Patterns by image type, style rules, and where to add alt text on each platform. Read it first. |
| `scripts/alttext.mjs` | Step 3. Checks a CSV of alt texts and prints a report. `--out` never overwrites. Needs Node.js 18+. |
| `examples/` | Sample alt texts with mistakes, the fixed versions, both reports, notes on what the images show, a walkthrough and test runs. |

## Step 1: Gather the images and context

- The images (look at each one), and the platform for each.
- The post's purpose: what the image is doing there (showing the product, announcing a sale, explaining a tip).
- Names, if any people should be named.

## Step 2: Write

Use the pattern for each image type in `references/alt-text-guide.md`. Start with the subject, put the key detail first, and keep photos to about 125 characters. Transcribe text images. Give each carousel slide its own alt text.

Write them to a new CSV: `image,platform,type,alt`.

## Step 3: Check

```
node <skill-folder>/scripts/alttext.mjs alt-texts.csv [--out report.md]
```

Fix every FAIL. Fix the WARNs unless there's a reason not to, for example a long description for an infographic. Run it again.

**No Node.js?** Check by hand against the style list in the guide, and say the script wasn't run.

## Step 4: Hand over

1. The alt text for each image, ready to copy.
2. Where to paste it on each platform (from the guide's table).
3. Any image where you need the user's input, such as a person's name or text you couldn't read.