Content
77%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.
The body is exceptionally actionable — every instruction comes with an exact command, complete code sample, or worked naming example, and the search-write-validate-retry workflow is a model feedback loop. Weaknesses are structural and editorial: a large wall of domain rules is inlined into SKILL.md instead of being split into reference files, and the mandatory tool-call instructions are duplicated across two sections with heavy repetitive emphasis. Splitting the Rust/GraphQL deep-dive into references and de-duplicating the workflow instructions would raise both conciseness and progressive disclosure without losing any value.
Suggestions
Move the long Rust codegen rules ('Important notes for Rust function logic', scalar types table) and the GraphQL input-query notes into one-level-deep reference files (e.g., references/rust-notes.md, references/graphql-input.md), keeping SKILL.md as an overview with clearly signaled pointers.
De-duplicate the mandatory workflow: the 'Required Tool Calls' section and the two trailing 'MANDATORY' sections repeat the same search/validate instructions — merge them into a single section and drop the repeated privacy notices into one note.
Trim ALL-CAPS emphasis stacking ('VERY IMPORTANT', 'THIS IS A MUST', 'Never ever ever') to a single emphatic statement per rule; the rules themselves are valuable and remain enforceable without the repetition.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Most of the body is dense, non-obvious domain knowledge Claude does not already have (Rust codegen naming rules, scalar handling, GraphQL input-query quirks), so it is mostly efficient. However, it could be tightened: the mandatory search/validate tool-call workflow is stated twice in full (the 'Required Tool Calls' section and the two 'MANDATORY' sections at the end), emphasis is padded with shouting ('THIS IS A MUST', 'Never ever ever'), and two separate privacy notices repeat near-identical text — matching 'mostly efficient but includes some unnecessary explanation or could be tightened'. | 3 / 5 |
Actionability | Fully executable throughout: exact CLI commands ('shopify app generate extension --template <api_lowercase_and_underscore> --flavor <rust|vanilla-js|typescript> --name=<function_name>'), complete copy-paste Rust snippets (main.rs with #[typegen]/#[query], Configuration struct with metafield deserialization), a full GraphQL input-query example, and concrete naming-convention worked examples (FunctionFetchResult -> fetch() -> src/fetch.rs). Not below 5: the common cases (run/fetch targets, multi-target functions, metafield configuration) are all covered with runnable code. | 5 / 5 |
Workflow Clarity | The workflow is an explicit ordered sequence with validation checkpoints and a feedback loop: 1) search docs, 2) write code, 3) validate with scripts/validate.mjs, 4) on failure search the error type, fix, re-validate (max 3 retries), 5) return code only after validation passes. This matches the top anchor ('clear sequence with explicit validation steps; feedback loops for error recovery'), including the detailed error-recovery loop in 'Validate Before Returning Code'. | 5 / 5 |
Progressive Disclosure | There is real bundle structure — scripts/search_docs.mjs and scripts/validate.mjs are referenced by exact path and both exist, and assets/ holds 13 per-API doc bundles — but the 300+ lines of Rust/GraphQL domain rules are inlined monolithically inside a single <system-instructions> block in SKILL.md rather than split into one-level-deep reference files, and the assets/ doc bundles are never surfaced or navigable from the body. This matches 'some structure but could be better organized; content that should be separate is inline'. | 3 / 5 |
Total | 16 / 20 Passed |