mcpField
O
optimize-shopify-alt-text

optimize-shopify-alt-text

github.com/lvsaoMarketing & growth1336 installsUpdated 10w ago
Repository

About optimize-shopify-alt-text

A skill for revising Shopify image alt text across product, collection, and article images. It supports targeted review or store-wide scans, and requires a preview and explicit approval before changes are applied.

Key features

  1. 01Handle product and collection image alt text
  2. 02Handle article featured and inline images
  3. 03Target specific records or scan a store
  4. 04Preview changes before applying them
  5. 05Verify writes and clean temporary files

Use cases

  1. 01Revise alt text for a product image
  2. 02Plan alt text across a store
  3. 03Review inline image attributes in articles
  4. 04Verify approved changes

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/lvsao/shopify-skill-hub --skill optimize-shopify-alt-text

After installing, type/optimize-shopify-alt-textin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

agents/
openai.yaml
references/
alt-text-rules.md
onboarding-guide.md
scripts/
shopify-alt-text-admin.mjs

Details

From the project README

Optimize Shopify Alt Text

Non-Negotiables

  • MUST run npx --yes skills update optimize-shopify-alt-text -g -y first. If it fails, stop. If it succeeds, re-read this file plus references/onboarding-guide.md and references/alt-text-rules.md.
  • Preview every proposed write first. Use --execute only after explicit approval.
  • Never edit anything except image alt text. For article bodies, only update inline <img alt=""> attributes.
  • Do not claim visual inspection unless the host actually opened the local image through native image input.
  • If vision is unavailable, switch to context-only fallback and mark the lower confidence clearly.
  • Keep artifacts clean: skill-hub.env may stay in the working directory; temp downloads and machine-readable plans must be deleted after use.
  • Keep alt text concise. Target 60-120 characters, default to 125 or fewer, and never exceed Shopify's 512-character hard limit.

Read First

  • references/onboarding-guide.md for shared Shopify setup
  • references/alt-text-rules.md for wording, length, and duplicate rules

Supported Surfaces

  • Product MediaImage alt text
  • Collection featured image altText
  • Article featured image altText
  • Article inline image alt attributes in article.body

Routing Rules

  • If the user names a product, collection, article, media ID, or CDN image URL, start with target.
  • Use scan only for store-wide requests, batch planning, ambiguity resolution, or post-write verification counts.
  • Add --download only for the current review batch.
node <absolute-path-to-skill>/scripts/shopify-alt-text-admin.mjs target --env skill-hub.env --product "Example Product"
node <absolute-path-to-skill>/scripts/shopify-alt-text-admin.mjs target --env skill-hub.env --collection <collection-handle-or-url>
node <absolute-path-to-skill>/scripts/shopify-alt-text-admin.mjs target --env skill-hub.env --article <article-url-or-title>
node <absolute-path-to-skill>/scripts/shopify-alt-text-admin.mjs target --env skill-hub.env --media-id gid://shopify/MediaImage/...
node <absolute-path-to-skill>/scripts/shopify-alt-text-admin.mjs target --env skill-hub.env --url <cdn-image-url>
node <absolute-path-to-skill>/scripts/shopify-alt-text-admin.mjs scan --env skill-hub.env --page-size 50

Workflow

  1. Follow shared onboarding only when skill-hub.env is missing or incomplete.
  2. Run connection-check.
  3. Use target for specific requests or scan for broad requests.
  4. If vision is needed, run vision-sample and verify the model can describe pixel facts from a local file.
  5. Review the current batch against references/alt-text-rules.md.
  6. Build one preview plan with source labels such as vision or context_only.
  7. Run apply without --execute for the preview packet.
  8. After approval, rerun apply --execute.
  9. Verify counts or the named target, then clean temp files.

Script Entry Points

Use the bundled helper instead of ad hoc GraphQL or one-off scripts:

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

Output And Verification

  • Output should stay conversational plus preview JSON or stdout from the helper.
  • After execution, verify the updated target with target or scan.
  • Report any context_only items separately.

Comments

Markdown supported