managing-shopify-app-listing

name	managing-shopify-app-listing
description	Manage a Shopify App Store listing through a private local workflow that captures current fields, opens a PR-style localhost review app, and applies approved text/config changes with agent-browser. Use when editing or auditing a Shopify listing from the listing admin.
disable-model-invocation	true

Managing Shopify App Listing

Overview

Use this skill to manage one or more Shopify App Store listings without leaking private listing data into the repo. Keep all real data in .local/shopify-listing/, use the review app for approval, and only then apply changes with agent-browser. The workflow bootstraps .local/shopify-listing/ as a private git repo automatically the first time you run a main CLI command.

Preconditions

• Ensure agent-browser is installed. On macOS, prefer brew install agent-browser && agent-browser install.
• Run a headed Shopify login once so the repo-local browser profile is authenticated.
• Copy examples/config.example.json to .local/shopify-listing/config.json and adjust the local config.
• When multiple apps or languages are configured, pass --app <app-key> and --locale <language-key>.

Workflow

0. Login

Bootstrap the repo-local browser profile:

npm run login -- --app <app-key>

Complete Shopify login in the opened browser window. Future commands will reuse .local/shopify-listing/browser-profile/. On macOS, this opens Google Chrome for Testing, not your normal Chrome profile. After that initial login, normal capture, review, and apply runs should stay headless and reuse the saved profile automatically.

1. Draft

Create or refresh the desired-state template:

npm run draft -- --app <app-key> --locale <language-key>

Edit .local/shopify-listing/apps/<app-key>/locales/<language-key>/desired.json directly, use the localhost workspace draft editor, or let the LLM prepare updates there.

2. Capture

Capture the current listing admin state:

npm run capture -- --app <app-key> --locale <language-key>

This writes app- and language-specific files under .local/shopify-listing/apps/<app-key>/locales/<language-key>/. Capture runs headless by default and reuses .local/shopify-listing/browser-profile/. The capture also stores field constraints like Shopify character limits so the local draft stays valid.

3. Review

Generate the diff and start the localhost review app:

npm run review -- --app <app-key> --locale <language-key>

For a broader workspace view, start:

npm run preview -- --app <app-key> --locale <language-key>

Use /workspace/current, /workspace/draft, /workspace/diff, and /workspace/history to inspect production, edit the local draft, review constraints, and inspect version history. Prefer the workspace review route that stays tied to the active app and locale. If you open a review session directly, keep the session-id visible and use that exact id for status checks and apply.

Review the proposal in the browser and record either:

• Approve
• Request changes

Poll the review decision from another terminal:

npm run review:status -- --session <session-id>

Treat this as mandatory after clicking Approve or Request changes. The review UI now gives immediate save feedback, but use review:status to confirm state in a second terminal when needed.

• Before approving or applying, confirm that the diff is fully valid: changedCount == readyCount, and both invalidCount and unsupportedCount are 0.

4. Apply

Apply only an approved review:

npm run apply -- --session <session-id>

Apply will re-capture current state first and abort if the reviewed base state has drifted. Apply now writes tracked evidence into the locale's changes/ and screenshots/ directories, then automatically commits draft/state changes and creates an annotated tag locally.

Rules

• Keep all real listing data under .local/.
• Never apply without an approved review session.
• Always run npm run review:status -- --session <session-id> after the human approval click and before npm run apply.
• Do not apply when the current session diff has any blocked/invalid fields (invalidCount > 0 or unsupportedCount > 0).
• Treat Request changes as a hard stop and revise desired.json before trying again.
• Limit writes in v1 to text/config fields.
• Use languages[].editUrl in local config when Shopify language discovery needs a stable direct URL.
• Reuse the repo-local browser profile for every Shopify command.
• If .local/shopify-listing is a git repo, share the local commit + tag details produced by apply so the user can optionally prepare a PR.

References

• Field mapping guidance: references/field-map.md