| name | theme-development |
| description | Build, customize, and deploy Shopify themes. Use this skill for creating new themes, modifying existing themes, understanding theme architecture, working with sections/blocks, and optimizing theme performance. Covers Skeleton theme, Dawn theme, layouts, templates, and the theme editor customization experience. |
| license | MIT |
| compatibility | Requires Shopify CLI, Node.js 18+, and a Shopify Partner account |
| metadata | {"author":"shopify-agent-skills","version":"1.0","shopify-api-version":"2025-01"} |
Shopify Theme Development
When to use this skill
Use this skill when:
- Creating a new Shopify theme from scratch
- Modifying or customizing an existing theme
- Understanding Shopify theme architecture
- Working with sections, blocks, and templates
- Setting up the development environment
- Deploying themes to a Shopify store
- Optimizing theme performance
Theme Architecture Overview
Directory Structure
A Shopify theme must follow this structure:
your-theme/
├── assets/ # CSS, JS, images, fonts
├── config/ # Theme settings (settings_schema.json, settings_data.json)
├── layout/ # Layout files (theme.liquid required)
├── locales/ # Translation files (en.default.json, etc.)
├── sections/ # Reusable section components
├── snippets/ # Reusable code snippets
└── templates/ # Page templates (JSON or Liquid)
└── customers/ # Customer account templates
Minimum Requirements: Only layout/theme.liquid is required for upload.
Component Hierarchy
Layout (theme.liquid)
└── Template (product.json)
└── Sections (product-details.liquid)
└── Blocks (price, quantity, add-to-cart)
└── Snippets (icon-cart.liquid)
Getting Started
1. Initialize a New Theme
Use the Skeleton theme as a starting point:
shopify theme init my-theme
cd my-theme
The Skeleton theme is minimal and follows Shopify best practices.
2. Start Development Server
shopify theme dev
shopify theme dev --store your-store.myshopify.com
This opens a local preview URL with live reloading.
3. Push to Shopify
shopify theme push --unpublished
shopify theme push --theme THEME_ID
Key Concepts
Layouts
Layouts wrap all pages. The main layout file is layout/theme.liquid:
<!DOCTYPE html>
<html lang="{{ request.locale.iso_code }}">
<head>
<title>{{ page_title }}</title>
{{ content_for_header }}
</head>
<body>
{% sections 'header-group' %}
<main>
{{ content_for_layout }}
</main>
{% sections 'footer-group' %}
</body>
</html>
JSON Templates
Modern themes use JSON templates that reference sections:
{
"sections": {
"main": {
"type": "product-details",
"settings": {}
},
"recommendations": {
"type": "product-recommendations",
"settings": {}
}
},
"order": ["main", "recommendations"]
}
Sections
Sections are reusable, customizable modules:
<!-- sections/featured-collection.liquid -->
{% schema %}
{
"name": "Featured Collection",
"settings": [
{
"type": "collection",
"id": "collection",
"label": "Collection"
},
{
"type": "range",
"id": "products_to_show",
"min": 2,
"max": 12,
"step": 1,
"default": 4,
"label": "Products to show"
}
],
"presets": [
{
"name": "Featured Collection"
}
]
}
{% endschema %}
<section class="featured-collection">
{% if section.settings.collection != blank %}
{% for product in section.settings.collection.products limit: section.settings.products_to_show %}
{% render 'product-card', product: product %}
{% endfor %}
{% endif %}
</section>
Blocks
Blocks allow merchants to add, remove, and reorder content:
{% schema %}
{
"name": "Slideshow",
"blocks": [
{
"type": "slide",
"name": "Slide",
"settings": [
{
"type": "image_picker",
"id": "image",
"label": "Image"
},
{
"type": "text",
"id": "heading",
"label": "Heading"
}
]
}
]
}
{% endschema %}
{% for block in section.blocks %}
<div class="slide" {{ block.shopify_attributes }}>
<img src="{{ block.settings.image | image_url: width: 1920 }}">
<h2>{{ block.settings.heading }}</h2>
</div>
{% endfor %}
Best Practices
Performance
- Lazy load images - Use
loading="lazy" for images below the fold
- Optimize images - Use
image_url filter with appropriate widths
- Minimize render-blocking resources - Defer non-critical CSS/JS
- Use native browser features - Prefer CSS over JavaScript when possible
<!-- Responsive images with lazy loading -->
{{ product.featured_image | image_url: width: 800 | image_tag:
loading: 'lazy',
widths: '300, 500, 800, 1200',
sizes: '(max-width: 600px) 100vw, 50vw'
}}
Accessibility
- Use semantic HTML (
<main>, <nav>, <article>)
- Provide alt text for images
- Ensure proper heading hierarchy
- Support keyboard navigation
- Maintain sufficient color contrast
Theme Settings
Use settings_schema.json for global theme settings:
[
{
"name": "theme_info",
"theme_name": "My Theme",
"theme_version": "1.0.0"
},
{
"name": "Colors",
"settings": [
{
"type": "color",
"id": "primary_color",
"label": "Primary color",
"default": "#000000"
}
]
}
]
Access in Liquid: {{ settings.primary_color }}
CLI Commands Reference
| Command | Description |
|---|
shopify theme init | Clone Skeleton theme |
shopify theme dev | Start development server |
shopify theme push | Upload theme to store |
shopify theme pull | Download theme from store |
shopify theme check | Run theme linter |
shopify theme list | List all themes |
shopify theme publish | Publish unpublished theme |
shopify theme delete | Delete a theme |
Common Issues & Solutions
Issue: Theme not syncing changes
Solution: Ensure shopify theme dev is running and check for file save errors.
Issue: Section not appearing in editor
Solution: Add a presets array to the section schema.
Issue: Slow page load
Solution: Run shopify theme check and address performance warnings.
Resources
For Liquid templating specifics, see the liquid-templating skill.
