I wanted a way to give a coding agent a specific job: review a Shopify theme for performance problems, explain what it finds, and produce a report someone can work from.
That became Shopify Performance, a reusable agent skill that you can install with npx skills. It includes instructions for reviewing theme code, a report format, and a CLI helper for collecting Lighthouse results and Shopify Liquid profiles.
Giving the review some structure
The skill covers Liquid templates, sections, snippets, images, CSS, fonts, JavaScript, and app integrations. It asks the agent to follow how those pieces are used before reporting a problem.
That context matters. An image with lazy loading might be correctly configured further down the page. The same behaviour on the main product image could delay the content a shopper is waiting to see. A reusable section can also move around in the theme editor, so an assumption about its position needs checking.
The review considers Largest Contentful Paint (LCP), layout stability (CLS), interaction responsiveness (INP), and Time to First Byte (TTFB). It also asks the agent to distinguish something it can see in the code from something it has measured.
Finding a potentially expensive Liquid loop gives you somewhere to investigate. It doesn’t tell you how many milliseconds a rewrite would save.
Making the report useful
I added the report requirements because I wanted the output to explain how to resolve each issue.
Every finding should include where it occurs, why it matters, a recommended change, and a way to verify the result. The report starts with a plain-language summary and a priority table, then gives developers the file locations and implementation details.
For example, a finding about a delayed product image should explain what delays it, identify the relevant section or snippet, and describe how to check that the proposed change helps. It should also account for behaviour that needs to keep working, such as responsive image sizing or gallery interactions.
The skill reviews by default. If you ask it to make fixes as well, the report should distinguish suggested changes from changes it applied and checked.
Adding Lighthouse and Liquid measurements
I extended the skill with a Python helper so the agent can include measurements alongside its code review.
For Lighthouse, the helper runs repeated tests against a page and saves the scores, available metrics, median values, and ranges. It keeps the raw JSON results so you can inspect the evidence behind the summary.
The Liquid workflow uses Shopify’s theme profile command. It saves a Speedscope profile and summarises the rendering frames by self time and inclusive time.
These measurements answer different questions. Lighthouse examines the page in a browser. Liquid profiling helps identify where the remote theme spends time rendering on Shopify.
The report keeps those results separate. It also records failures and unavailable metrics rather than presenting them as successful measurements.
Installing and using it
Run this from the project where you want to install the skill:
npx skills add JLTDigital/shopify-performance-skill --skill shopify-performance
Then give your agent a request such as: Use the Shopify performance skill to review this theme. Write a report explaining the issues, where they occur, how to fix them, and how to verify the improvements. Do not modify the theme.
You can start with the theme code alone. If you have measurements, point the agent to those files too.
For manual testing, clone the repository and follow the runtime guide. It includes setup instructions, copyable commands, parameter tables, and examples for homepages, product pages, and collection pages.
The measurement helper needs Python and the relevant CLIs installed separately. Liquid profiling also requires an authenticated account with access to the store and theme. It profiles the remote theme, so local changes won’t appear until they have been uploaded.
Where it stands
The helper has 12 passing automated tests covering timing calculations, missing metrics, malformed profiles, and partial failures. I’ve also checked that the package installs with the skills CLI.
Live validation is still incomplete. The Lighthouse smoke test couldn’t connect to Chrome in the environment used to build it, and the Liquid workflow still needs an authenticated store test. I haven’t measured a storefront improvement from the skill yet.
The repository is public under the MIT license. You can download it, try it on a theme, or suggest an improvement. If you find a review rule that produces a misleading result, an anonymised code example would help me improve it.