/shopify-alt-text

name: shopify-alt-text
description: >-
  Use when backfilling missing image alt text on a Shopify store: images with no
  alt attribute, accessibility alt text for product images, alt text for Files
  library images, image SEO, or a WCAG/accessibility pass that flags images
  missing text alternatives. Triggers: "backfill alt text", "fill in missing alt
  text", "images have no alt", "add alt attributes for accessibility", "image
  SEO sweep". One mutation, fileUpdate, covers both product media and the Files
  library. Not for meta titles/descriptions (use shopify-seo-metadata).
compatibility: >-
  Requires Shopify Admin API access (custom-app token or Shopify CLI 3.x).
  GraphQL written against Admin API 2025-07. Scopes: `read_products` to enumerate
  product-image owners, `read_files` to page the Files library, `write_files`
  because `fileUpdate` writes alt for both.

Shopify Alt Text

Backfill missing image alt text across a Shopify store. Alt text is an accessibility requirement first (screen readers announce it) and an image-SEO signal second. This skill fills the gap for images that have none; it does not rewrite alt text that already exists.

The sister backfill for SEO titles and descriptions is **shopify-seo-metadata**: same safe-mode doctrine, different fields. The FIND stage (measuring how many images lack alt across the catalog before you commit to a sweep) belongs to **shopify-catalog-audit**.

One mutation, two find paths

Images live in two places on a Shopify store, but both write through the **same mutation**. A product image and a Files-library image are both `MediaImage` nodes, which are `File` subtypes, so a single `fileUpdate` sets `alt` on either. There is no separate product-media alt mutation to learn.

• **`fileUpdate` is the one write.** It takes the image's `MediaImage` GID and

the new `alt`. This is the write path both source tools converge on. (Shopify's old `productUpdateMedia` is **deprecated on shopify.dev; do not use it** for alt text.)

• **Two ways to FIND the images, one way to fix them:**
• *Product media:* page products, read each `MediaImage` under `product.media`.

Needs `read_products`.

• *Files library:* page the `files` connection (Content → Files: theme

sections, metaobjects, rich-text, collection banners). Needs `read_files`.

• Both hand you `MediaImage` GIDs; feed those straight into `fileUpdate`.

Full count/fetch/update/verify recipes for both find paths are in [references/queries.md](references/queries.md).

Store access

Every skill that touches the Admin API opens with this stanza. Two lanes; pick one.

**Lane A, custom-app token (scriptable).** In Shopify admin: Settings → Apps and sales channels → Develop apps → create an app → grant the minimum scopes below, then install and copy the Admin API access token. Export it; never write it to a committed file:

export SHOPIFY_STORE="your-store.myshopify.com"
export SHOPIFY_ACCESS_TOKEN="<your Admin API access token>"   # keep it in the env, not on disk

Call the GraphQL endpoint (minimum scopes for this skill: `read_products` to enumerate product-image owners, `read_files` to page the Files library, and `write_files` because `fileUpdate` writes alt for both):

curl -s "https://$SHOPIFY_STORE/admin/api/2025-07/graphql.json" \
  -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ shop { name } }"}'

**Lane B, Shopify CLI OAuth (no stored token).** `shopify store auth --store $SHOPIFY_STORE --scopes read_products,read_files,write_files` then `shopify store execute` to run a validated operation. Good for token-less stores where the owner logs in interactively.

**Toolkit preflight.** Lane B rides on the Shopify CLI: run `shopify version` first and install it if missing. For the full Admin GraphQL schema and validated execution, pair this skill with Shopify's official AI toolkit plugin. In Claude Code, check `claude plugin list`; if it isn't there:

claude plugin marketplace add Shopify/Shopify-AI-Toolkit
claude plugin install shopify-plugin@shopify-ai-toolkit

Recommended, not required: Lane A needs only curl and a token. The toolkit gives your agent the API; this skill gives it the playbook.

Recipes, not scripts

This is a **recipe, not a program.** The GraphQL blocks in the reference are copy-and-adapt starting points: write throwaway code per engagement against the current schema, run it, discard it. Do not ship a standing binary that silently rots when Shopify changes the schema.

Safe-mode / preview / verify doctrine

State it standalone, run it every time. This is a bulk write against a live store; the difference between a clean sweep and a support ticket is discipline.

1. **Fill missing only, never overwrite.** Treat an image as a candidate only when its `alt` is null or empty after trimming whitespace. An image that already has alt text, even mediocre alt text, is out of scope. Overwriting existing alt is a separate, deliberate decision a human makes per-image, never the default of a sweep. 2. **Preview a read-only count first.** Before any mutation, run the count query for the find path you are about to touch and read the number back. Sanity-check it: a store with 300 products and "1,900 product images missing alt" is plausible; "40,000 missing" on the same store means your filter is wrong (probably counting non-image files or already-captioned images). A count far above expectation means stop and re-scope, not proceed. 3. **Preflight the generation API key with a real 1-token completion.** If you caption images with an LLM, before the bulk run send one real (cheap, 1-token) completion and confirm a 200. Do **not** trust a `models.list` / auth-only check: a key that lists models can still fail on the actual completion (billing, per-model access, org limits), and you find out 400 images into the sweep instead o