Content
78%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, highly actionable reference: every command is executable, the API-specific gotchas (scopes, GIDs, rate-limit costs, token formats) are genuinely non-obvious, and destructive operations are gated by an explicit safety section. The main structural weakness is that all of it lives in one large SKILL.md with no progressive disclosure into reference files, and a little time-sensitive editorial material sits outside a dedicated section.
Suggestions
Split the per-resource examples (orders, customers, inventory, metafields, webhooks, bulk operations) into references/*.md files, keeping SKILL.md as setup, the base curl pattern, and pitfalls.
Add inline validation checkpoints to the mutation flows (e.g. verify `product.id` is non-null and `userErrors` is empty before running `productVariantsBulkCreate`).
Consolidate date/version-sensitive notes (2026-01 API version, Jan 2026 legacy-app deprecation, frozen REST API) into a single 'Deprecated / time-sensitive' section.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and operational — scope lists, auth headers, GID formats, rate-limit costs, and pitfalls are non-obvious specifics Claude cannot know — with almost no padding of known concepts. Not 5 because of a few editorial lines ('No SDK, no app framework', 'Pipe through jq for readable output') and time-sensitive details (2026-01 versions, the Jan 2026 legacy-app cutoff) that sit in intro/callout text rather than a dedicated deprecation section. | 4 / 5 |
Actionability | Everything is copy-paste executable: a reusable `shop_gql` curl/jq function, fully formed GraphQL queries with `$variables` JSON, and worked examples for every common case (search, paginate, create, update, inventory adjust/set, metafieldsSet, bulk operations, webhooks). Matches the 'fully executable; copy-paste ready; specific examples cover the common cases' anchor. | 5 / 5 |
Workflow Clarity | Multi-step processes are clearly sequenced — a numbered prerequisites flow, the 3-step bulk-operation lifecycle with status polling, and pagination with cursor passing — plus explicit validation guidance ('Always check both' `errors` and `userErrors`) and a Safety section requiring confirmation before destructive mutations. Not 5 because validation is stated as a principle rather than an inline validate-fix-retry checkpoint in each flow (e.g. no explicit verify-product-created step before chaining variant creation). | 4 / 5 |
Progressive Disclosure | Sections are clearly organized (API Basics, per-resource sections, Pitfalls, Safety), but this is a single 345-line file with no bundle files at all — the per-resource example library (products, orders, customers, inventory, metafields, webhooks, bulk) is inlined content that clearly belongs in separate reference files. Fits 'some structure but could be better organized; content that should be separate is inline'; not 4 because there is no split at all, and not 2 because the internal structure is strong, not minimal. | 3 / 5 |
Total | 16 / 20 Passed |