Xây dựng app và theme Shopify với ak:shopify

Dùng ak:shopify để triển khai hoặc tinh chỉnh Shopify app, UI extension, Function, theme hay Admin API integration. Skill cung cấp pattern cho GraphQL, OAuth, session token, webhook, app billing, Liquid, Shopify CLI cùng kiểm thử theo platform.

Chọn đúng bề mặt Shopify

Dùng ak:shopify khi

• Bạn xây app tích hợp service hoặc quản lý store data.
• Bạn cần extension checkout, admin, POS, customer account hoặc theme app.
• Bạn cần Shopify Function cho discount, payment, delivery hoặc validation.
• Bạn đang đổi Liquid theme, section, snippet, storefront interaction hay theme deployment workflow.

Chọn workflow khác khi

• Task là commerce website tổng quát không dùng Shopify. Dùng workflow frontend hoặc backend phù hợp.
• Yêu cầu product, billing, privacy, data retention hoặc app distribution chưa rõ. Giải quyết chúng trước code mutation.
• Bạn chỉ cần visual direction cho storefront. Dùng ak:frontend-design trước theme implementation.
• Bạn cần review độc lập cho thay đổi hiện có. Dùng ak:code-review, ak:test hoặc ak:security.

Chuẩn bị store, API version và tool

Trước khi bắt đầu:

• Hoàn thành Làm quen và xác nhận Engineer Kit đã được cài cho runtime cùng scope hiện tại.
• Xác định target là app, extension, Function hay theme; đừng ngầm trộn deployment model của chúng.
• Đọc version Shopify CLI, framework, UI extension, Liquid và Admin API đã cài từ project, rồi xác minh tài liệu cùng deprecation hiện tại của Shopify.
• Dùng development store, test app, test product/order cùng access scope tối thiểu. Giữ API secret, access token, session token, webhook secret và customer/order data ngoài prompt, log, client code cùng Git.
• Xác định tệp, remote store, webhook topic, billing behavior, test account được phép, cùng quyền CLI login, tạo tunnel, store sync, deploy, push hay publish.

Reference đi kèm là snapshot platform tháng 1 năm 2025. API version, extension target, component API, CLI output cùng store requirement phải được kiểm tra với project hiện tại và contract hiện tại của Shopify.

Xem Runtime adapter để hiểu khác biệt theo từng component.

Chạy Skill

Argument shape được khai báo là [extension-type] [feature], nhưng bạn có thể nêu app, function hoặc theme khi đó là target thực tế.

/ak:shopify "checkout_ui_extension Add an optional gift message to the existing app. Preserve its pinned API version and scopes, validate and store the attribute through current project patterns, add focused tests, use only the development store, and do not deploy or publish."

/ak:shopify "checkout_ui_extension Add an optional gift message to the existing app. Preserve its pinned API version and scopes, validate and store the attribute through current project patterns, add focused tests, use only the development store, and do not deploy or publish."

$ak:shopify "checkout_ui_extension Add an optional gift message to the existing app. Preserve its pinned API version and scopes, validate and store the attribute through current project patterns, add focused tests, use only the development store, and do not deploy or publish."

Quan sát các giai đoạn Shopify

1. Lần chạy xác định đúng bề mặt. Skill lập bản đồ app, extension, Function hoặc theme layout hiện tại, generated file, configuration, API version cùng store boundary.
2. Lần chạy xác minh platform support hiện tại. Extension target, GraphQL field, access scope, Liquid behavior, CLI command cùng plan restriction được kiểm tra trước implementation.
3. Lần chạy xác định data và security behavior. OAuth state, session token, webhook HMAC, customer data, billing confirmation, error state cùng cleanup behavior luôn rõ ràng.
4. Lần chạy triển khai local change nhỏ nhất. Skill tuân theo generated-file rule cùng scaffolding hiện có thay vì thay app bằng reference tổng quát.
5. Lần chạy xác minh trên đúng boundary. Static check chạy local; development-store, extension, webhook, theme, mobile cùng accessibility behavior chỉ được kiểm tra với test access đã duyệt.
6. Lần chạy báo cáo remote effect. Tệp đổi, scope, generated output, store object, preview link, CLI session cùng bước deployment hoặc publication chưa làm luôn hiển thị.

Giữ store mutation và publication dưới quyền duyệt

• Chỉ yêu cầu access scope cần thiết và đánh giá lại khi cách dùng data đổi. Coi customer cùng order data là dữ liệu nhạy cảm.
• Xác minh OAuth state và webhook HMAC bằng request byte thật trước processing. Giữ webhook handler idempotent và chỉ acknowledge theo contract Shopify hiện tại.
• GraphQL query và mutation phải xử lý pagination, user error, throttling cùng versioned schema change.
• Initializer tùy chọn đi kèm là local generator nhẹ, không phải scaffolding chính thức của Shopify. Với app cùng extension, nó tạo hoặc overwrite config, README và package file trong directory cùng tên; với theme, nó chỉ in lệnh shopify theme init được khuyến nghị.
• shopify app deploy, theme push, live pull cùng theme publish nằm ngoài local implementation thông thường trừ khi được cấp quyền riêng.

Xác minh kết quả

Kết quả hoàn tất nên cung cấp:

• Bề mặt Shopify đã chọn, bằng chứng API/CLI hiện tại, loại store identity không kèm secret cùng user-visible behavior.
• Chính xác changed/generated file, dependency change, scope, webhook topic, GraphQL operation, theme asset cùng remote object.
• Bằng chứng typecheck, unit, component, Function, shopify theme check, webhook, development store, accessibility cùng responsive tập trung khi áp dụng.
• Bằng chứng cho authentication failure, GraphQL user error, throttling, duplicate webhook, uninstall/privacy cleanup, billing cancellation hoặc theme rollback khi liên quan.
• Xác nhận không live deploy hay publish trừ khi được cấp quyền rõ ràng, cùng checklist review và rollout còn lại.

Xử lý sự cố hoặc tiếp tục

Tiếp tục với ak:frontend-development cho embedded React UI, ak:payment-integration cho external payment provider có scope riêng hoặc Tổng quan Engineer Kit cho delivery được điều phối.

Biết các giới hạn hiện tại

• Skill không cấp quyền Partner, Admin, development store, billing, customer hay App Store.
• Reference không chứng minh API field, plan entitlement, review rule, rate limit, extension availability hay CLI behavior hiện tại.
• Ví dụ đi kèm là pattern chưa đầy đủ, không phải OAuth library, privacy program, billing ledger, webhook queue, theme rollback system hay app review checklist hoàn chỉnh.
• Test đi kèm kiểm tra initializer nhẹ, không kiểm tra Shopify app, store, extension, Function, theme, webhook hay deployment thật.
• Stable và beta chứa nội dung Skill cùng resource giống nhau trong cặp release này. Diagnostic Codex Hook của beta không thay đổi workflow này.