Optimize Shopify Alt Text

Non-Negotiables

Use Shopify Admin GraphQL only after verifying access with the bundled helper.
Preview proposed changes before asking for confirmation. Execute writes only after explicit user approval.
Never publish content, edit product copy, replace images, delete files, or change article body text other than inline image
```
alt
```
attributes.
Do not trust a model's self-report about image capability. Test whether the active model can inspect a local image before using the multimodal path.
If image understanding is unavailable, use context-only fallback and mark lower confidence. Do not pretend the model inspected pixels.
Downloading an image is not image inspection. The agent must actually open, attach, or view the local image through the host model's native image input or image-view tool before claiming visual understanding.
Never generate a
```
vision
```
alt text from product title, collection title, article title, filename, URL, or surrounding context alone. That is context-only fallback.
Do not create process notes, summary documents, ad hoc code files, or persistent JSON files in the user's working folder. Use stdout/stdin or the operating system temp directory, then delete temp files immediately.
Keep alt text concise: target 60-120 characters, keep 125 characters or fewer by default, and never exceed Shopify's 512-character maximum.
Prefer
```
fileUpdate
```
for product
```
MediaImage
```
alt text.
```
productUpdateMedia
```
is deprecated.
Preserve existing image URLs when updating collection featured images and article featured images.
Keep the user's working folder clean. The only expected local config file is
```
skill-hub.env
```
; all temporary downloaded images or machine-readable plans must live outside the working folder or be streamed through stdin, then be deleted immediately.
Never print or store access tokens, client secrets, short-lived tokens, session cookies, or real merchant data in public files.

Read

references/alt-text-rules.md

before generating or reviewing alt text candidates.

Beginner Onboarding First

Before asking any setup question, inspect the local environment first:

Identify the current working directory from the active terminal or host environment. This is the folder the user is working in, not the installed skill folder.
Look for the exact filename
```
skill-hub.env
```
in that current directory. Use whatever direct file check, directory listing, or direct file-read tool is reliable in the current host.
Do not rely on a broad search or glob result as the only evidence that the file is missing. If a search says "not found" but the user, file explorer, terminal, or direct path suggests the file exists, re-check by listing the current directory or reading the exact
```
skill-hub.env
```
path.
If it exists, read only the variable names and whether required values are present. Do not print secrets.

SKILL_HUB_SHOPIFY_ACCESS_METHOD

admin_custom_app

and the store domain plus Admin API token are present, run

connection-check

SKILL_HUB_SHOPIFY_ACCESS_METHOD

dev_dashboard_app

and the

.myshopify.com

store domain plus Client ID are present, run

connection-check

If
```
connection-check
```
succeeds, continue directly to scan and vision probe. Do not ask where the app was created.
If the user says "already configured", "B is configured", or similar, treat that as a request to inspect
```
skill-hub.env
```
, not as an A/B answer.

Ask the setup question only when

skill-hub.env

is missing, incomplete, placeholder-only, or the access method cannot be determined:

text

Where did you create your Shopify app?

A - Shopify store Settings custom app (Legacy Custom App)
B - Dev Dashboard app

Then create or update one private shared file in the current working directory:

text

skill-hub.env

Immediately ensure

.gitignore

contains

skill-hub.env

. Do not ask the user to create the env file or update

.gitignore

manually.

Path A: Shopify Store Settings Custom App (Legacy Custom App)

Create the env file with:

powershell

node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs init-env --method admin_custom_app --env skill-hub.env

Ask the user to fill only:

SKILL_HUB_SHOPIFY_STORE_DOMAIN

: the store domain the merchant knows, such as

example.com

example.myshopify.com

```
SKILL_HUB_SHOPIFY_ADMIN_API_ACCESS_TOKEN
```
: the Admin API token from the Shopify custom app.

Required scopes:

text

read_products,write_products,read_content,write_content,read_files,write_files

Path B: Dev Dashboard App

Create the env file with:

powershell

node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs init-env --method dev_dashboard_app --env skill-hub.env

Ask the user to fill only:

SKILL_HUB_SHOPIFY_STORE_DOMAIN

: the store's exact

.myshopify.com

domain.

```
SKILL_HUB_SHOPIFY_CLIENT_ID
```
: the app Client ID from Dev Dashboard settings. This is used for Shopify CLI config link and deploy.

Do not ask for the Client secret for this workflow unless a future helper explicitly implements client credential token exchange. The bundled helper uses Shopify CLI store authorization after deploy.

Check Node.js, npm, and Shopify CLI:

powershell

node -v
npm -v
shopify version
shopify store --help

If Shopify CLI is missing or too old for

shopify store

, run:

powershell

npm install -g @shopify/cli@latest

Then configure scopes through Shopify CLI. Do not ask the user to manually enter scopes in Dev Dashboard.

Do not run

shopify store list

shopify auth status

; these are not valid diagnostics for this workflow in current Shopify CLI. Do not repeatedly run manual

shopify store execute

commands for scan or write work.

powershell

$tmp = Join-Path $env:TEMP ("skill-hub-shopify-app-" + [guid]::NewGuid().ToString("N"))
New-Item -ItemType Directory -Path $tmp | Out-Null
shopify app config link --client-id <client-id> --path $tmp --no-color

Edit only

$tmp\shopify.app.toml

toml

[access_scopes]
scopes = "read_products,write_products,read_content,write_content,read_files,write_files"

Then run:

powershell

shopify app config validate --path $tmp --no-color
shopify app deploy --client-id <client-id> --path $tmp --allow-updates --no-color

After deployment, do not send the user to Dev Dashboard to look for a manual approval button. Instead, run Shopify CLI store authorization with the required scopes. Tell the user before running it: "A Shopify permission authorization page may open next. Please review the scopes and click authorize."

powershell

shopify store auth --store <store>.myshopify.com --scopes read_products,write_products,read_content,write_content,read_files,write_files --json --no-color

Verify after the browser authorization:

powershell

node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs connection-check --env skill-hub.env

Always remove the temporary CLI app config directory after setup succeeds or fails.

Shopify Surfaces

This skill scans and writes only these surfaces:

Product media images: read products and
```
MediaImage
```
; write alt text with
```
fileUpdate
```
.
Collection featured images: read
```
collection.image
```
; write
```
collectionUpdate(input.image.altText)
```
while preserving the current image URL.
Article featured images: read
```
article.image
```
; write
```
articleUpdate(article.image.altText)
```
while preserving the current image URL.
Article inline images: read
```
article.body
```
; update only
```
<img alt="...">
```
attributes inside the body HTML with
```
articleUpdate(article.body)
```
.

Vision Capability Probe

Before generating multimodal alt text, test the active model on a known local image.

The probe must force real image input. Use the host environment's native image mechanism, for example a local image attachment, a file-view image tool, or another explicit multimodal image input. A shell command such as

curl

dir

Get-Item

, metadata extraction, OCR library, filename parsing, or product-title lookup does not count.

Use a prompt like:

text

Tell me what is visible in this local image: <absolute image path>.
Answer from the image pixels only. Do not use OCR libraries, filenames, metadata, surrounding text, or guesses.
Return VISION_UNAVAILABLE if you cannot inspect the image directly.

Evaluate the answer against expected visual facts for the test image. Do not ask "are you multimodal?" and do not trust a yes/no self-report.

The answer must include at least three visual facts that are not inferable from filename, URL, product title, collection title, article title, or nearby text. Examples: object type, color, layout, background, visible text, material, shape, or scene. If the answer only restates Shopify context, product names, filenames, or generic ecommerce assumptions, the probe failed.

Before using context-only fallback, the agent must download at least one real image from the current Shopify scan, open the local file with the host-native image input path, and report at least three pixel-derived facts. If that succeeds, use Strategy A for every reasonably downloadable image in the current batch. If it fails, report exactly which layer failed: download, local image open, or pixel interpretation.

If the active model passes the probe, use Strategy A. If image download or host-native image opening fails, use Strategy B only for the affected item or batch.

Strategy A: Multimodal Image Understanding

Scan Shopify images.
Download only the current batch of image URLs to a temporary folder outside the working directory.
Open or attach each local image through the model's real image input before generating any visual description.
Ask for a visual description first, not the final alt text.
Require the visual description to include concrete pixel-derived facts. If the model mentions only product context, reject the result and retry with the actual image attached.
Generate final alt text from visual description plus Shopify page context.
Validate length, uniqueness, and confidence.
Delete downloaded images after the batch is reviewed.

If the model cannot inspect a downloaded image, mark that item as

vision_unavailable

and switch that item to context-only fallback.

Do not label an item

source: "vision"

unless the agent has actually inspected the downloaded/local image and can state pixel-derived evidence. If an item was inferred from title or fields, label it

source: "context_only"

even if an image URL was downloaded.

Strategy B: Context-Only Fallback

Use this when the active model cannot inspect images.

Generate candidates only from Shopify fields and nearby context. Mark each candidate with:

```
source: "context_only"
```
```
confidence: "high" | "medium" | "low"
```
```
reason
```

Context-only candidates are review-only by default. Do not mark context-only candidates as directly applicable with medium confidence. To apply a context-only candidate after explicit user approval, include

action: "approved_context_only"

in the apply plan.

Required Order

Create or verify
```
skill-hub.env
```
.
Run Shopify connection check.
Run a full scan and inventory count before generating alt text.
Run
```
vision-sample
```
, open at least one downloaded local image through the host-native image input path, and decide Strategy A or Strategy B from pixel evidence.
Build a batch plan. Default to 20-50 images per batch depending on user tolerance and model context.
Generate alt text candidates for the first batch.
Validate each candidate against
```
references/alt-text-rules.md
```
.
Show a concise preview plan.
Ask for explicit approval.
Apply only approved changes with
```
--execute
```
.
Verify by rescanning or reading changed resources.
Clean up temporary images and any operating-system temp files. Do not leave process JSON, generated scripts, or summary documents in the working folder.

Bundled Script

Use the bundled native Node.js helper. It uses only Node.js built-ins.

text

node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs init-env --method admin_custom_app --env skill-hub.env
node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs init-env --method dev_dashboard_app --env skill-hub.env
node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs connection-check --env skill-hub.env
node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs scan --env skill-hub.env --page-size 50
node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs vision-sample --env skill-hub.env --limit 3
node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs apply --env skill-hub.env --input -
node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs apply --env skill-hub.env --input - --execute

The

apply

command previews by default. Use

--execute

only after explicit user approval.

Do not use

shopify store execute

directly for scanning images or updating alt text, except for narrow troubleshooting. Direct terminal mutations are easy to run one image at a time, can stall in some IDE terminals, and bypass the helper's pagination, batching, duplicate checks, and cleanup rules. The helper internally uses Shopify CLI store auth when Path B is selected, runs Shopify CLI through its JavaScript entrypoint, uses query/output files, and cleans temporary CLI files.

The

vision-sample

command downloads 1-3 real Shopify images to an operating-system temp directory and prints their local paths. The agent must open those files with the host-native image input path, such as Read or an image-view tool, report at least 3 pixel-derived facts, and delete the temp folder after the probe.

Plan Input Contract

Prefer piping the approved plan JSON to

apply --input -

through stdin. Do not create

alt-text-plan.json

or other persistent process files in the user's working folder unless the user explicitly asks for a file artifact. If a temporary file is unavoidable, create it in the operating system temp directory and delete it immediately after the command returns.

json

{
  "batch": 1,
  "strategy": "multimodal",
  "changes": [
    {
      "type": "product_media",
      "id": "gid://shopify/MediaImage/...",
      "alt": "Black leather tote bag with gold zipper on a white background",
      "source": "vision",
      "confidence": "high",
      "visualEvidence": "Black tote bag, gold zipper, white background.",
      "reason": "The alt text is based on pixel-derived visual evidence plus product context.",
      "url": "https://cdn.shopify.com/..."
    },
    {
      "type": "collection_featured_image",
      "id": "gid://shopify/Collection/...",
      "alt": "Minimal skincare collection arranged on a bathroom counter",
      "source": "vision",
      "confidence": "high",
      "visualEvidence": "Skincare bottles, bathroom counter, neutral tile background.",
      "reason": "Preserves collection image URL and updates only altText.",
      "url": "https://cdn.shopify.com/..."
    },
    {
      "type": "article_featured_image",
      "id": "gid://shopify/Article/...",
      "alt": "Checkout optimization dashboard with conversion metrics",
      "source": "context_only",
      "confidence": "medium",
      "action": "approved_context_only",
      "reason": "Based on article title, summary, and filename.",
      "url": "https://cdn.shopify.com/..."
    },
    {
      "type": "article_inline_image",
      "id": "gid://shopify/Article/...#inline-0",
      "articleId": "gid://shopify/Article/...",
      "inlineIndex": 0,
      "alt": "Screenshot of a Shopify product media settings panel",
      "source": "vision",
      "confidence": "high",
      "visualEvidence": "Shopify product media settings panel, image thumbnail grid, white admin interface.",
      "reason": "Updates only the inline img alt attribute."
    }
  ]
}

Every

alt

must be non-empty and at most 512 characters.

Inventory And Batching

Always scan before writing. The scan output reports:

product count and product media image count
collection count and collection featured image count
article count, article featured image count, and article inline image count
how many images need optimization
shared product files that may affect multiple products if updated
whether the scan paginated through all products, collections, and articles

--page-size

is a page size, not a maximum. The helper keeps paging until Shopify reports no next page. Do not stop after the first page or after the first batch unless the user explicitly asks to pause.

Sort each batch by value and safety:

Missing product primary image alt.
Missing collection featured image alt.
Missing article featured image alt.
Missing article inline image alt.
Existing alt over the soft limit.
Repetitive or low-quality existing alt.
Lower-confidence context-only items.

If the scan finds more than one batch of work, do not try to optimize everything at once. Show the total count, estimated number of batches, and the first batch. After each approved batch, continue to the next batch or explicitly ask the user whether to pause. Do not silently stop after a partial batch.

Duplicate And Quality Gate

Before preview:

Reject alt text above 512 characters.
Rewrite alt text above 125 characters unless there is a strong accessibility reason.
Check duplicates within the same product, collection, or article.
Check generic patterns like repeated product title, comma-separated keyword lists, and "image of".
Reject any
```
source: "vision"
```
candidate that does not include concrete
```
visualEvidence
```
.
Mark all context-only items as review-only unless the exact candidate has explicit user approval and
```
action: "approved_context_only"
```
.
For shared product files, explain that a
```
fileUpdate
```
can affect every reference.

Safe Parallel Work

Use sub-agents only when the host environment supports them and only for independent read-only tasks.

Main agent only:

Create or edit
```
skill-hub.env
```
.
Handle credentials or tokens.
Validate Shopify access.
Download and delete temporary images.
Ask for approval.
Run
```
apply --execute
```
.
Verify writes.
Final cleanup.

Safe read-only sub-agent tasks:

Product media review: inspect product image candidates and propose alt text.
Collection image review: inspect collection featured images and propose alt text.
Article image review: inspect featured and inline images and propose alt text.
Duplicate/quality audit: compare proposed alt text for repetition and overlong copy.

Dependency order:

Main agent validates access and runs scan.
After scan, read-only image/context review can run in parallel by surface or batch.
Main agent merges results, validates limits, and shows one preview plan.
Main agent applies approved writes sequentially and verifies.

Do not parallelize Shopify writes. Do not let sub-agents handle secrets, create local scripts, create summary documents, write process JSON into the working folder, delete files, or perform final verification.

Preview Approval

Before any write, show:

target store
vision strategy: multimodal or context-only fallback
total inventory and selected batch size
proposed changes grouped by product, collection, and article
current alt and proposed alt
confidence and reason
visual evidence for every candidate marked
```
source: "vision"
```
character count for proposed alt
shared-file warnings
article body HTML warnings for inline image changes

Ask for explicit approval to apply the exact batch.

Verification And Cleanup

After writes:

Re-run
```
scan
```
or read the changed resources.
Confirm expected alt text exists.
Confirm article inline image
```
src
```
values were not changed.
Confirm no alt text exceeds 512 characters.
Confirm every
```
source: "vision"
```
change has visual evidence that came from actual image inspection.
Confirm low-confidence review-only items were not written unless approved.
Delete temporary image folders and downloaded images.
Confirm the working folder contains no process JSON, generated scripts, summary documents, or one-off helper files created during the run.

If cleanup fails, report the exact path that still needs removal.

Shopify API References

Verify current Shopify Admin GraphQL shapes before changing helper queries or mutations:

products

query:

https://shopify.dev/docs/api/admin-graphql/latest/queries/products

files

query:

https://shopify.dev/docs/api/admin-graphql/latest/queries/files

fileUpdate

https://shopify.dev/docs/api/admin-graphql/latest/mutations/fileUpdate

collectionUpdate

https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionUpdate

articles

query:

https://shopify.dev/docs/api/admin-graphql/latest/queries/articles

articleUpdate

https://shopify.dev/docs/api/admin-graphql/latest/mutations/articleUpdate

optimize-shopify-alt-text

NPX Install

Tags

SKILL.md Content

Optimize Shopify Alt Text

Non-Negotiables

Beginner Onboarding First

Path A: Shopify Store Settings Custom App (Legacy Custom App)

Path B: Dev Dashboard App

Shopify Surfaces

Vision Capability Probe

Strategy A: Multimodal Image Understanding

Strategy B: Context-Only Fallback

Required Order

Bundled Script

Plan Input Contract

Inventory And Batching

Duplicate And Quality Gate

Safe Parallel Work

Preview Approval

Verification And Cleanup

Shopify API References