Building a Custom Claude Code Skill for Shopify

Key takeaways

• A Claude Code skill is a folder with a SKILL.md file. The frontmatter tells Claude when to use it. The body tells Claude what to do.¹
• Personal skills live at ~/.claude/skills/<name>/SKILL.md. Project skills live at .claude/skills/<name>/SKILL.md and can be committed to git.¹
• Build a skill when you keep pasting the same Shopify checklist into chat. Install the Shopify AI Toolkit plugin when you need docs, schema validation, and store execution.²
• Claude loads a skill automatically when your request matches its description, or you invoke it directly with /skill-name.¹
• Keep SKILL.md under 500 lines. Move long reference material into separate bundled files.¹

This claude code shopify skill tutorial walks through building your own agent skill for Shopify work: a reusable SKILL.md file that scaffolds a Liquid section, checks it against your team’s rules, and loads only when you need it.

A skill is different from the Shopify AI Toolkit plugin. The plugin gives you Shopify’s docs, schema validation, and store execution. A custom skill encodes your conventions - your section patterns, your naming rules, your review checklist. This guide covers the second one. For plugin setup, see our Shopify AI Toolkit + Claude Code setup guide.

Why you can trust us

Jacques has over 15 years of development experience and has worked with hundreds of Shopify stores. We built Fudge - an AI-native Shopify store editor with a 5.0 rating and a Built for Shopify badge. We build agent skills and Claude Code workflows for Shopify daily.

What is a Claude Code skill?

A skill extends what Claude can do inside Claude Code. You create a SKILL.md file with instructions, and Claude adds it to its toolkit.¹

The mechanics are simple. The file has two parts: YAML frontmatter between --- markers that tells Claude when to use the skill, and markdown content with the instructions Claude follows when the skill runs.¹

Claude Code skills follow the Agent Skills open standard, which works across multiple AI tools.¹

How is a skill different from a plugin or MCP server?

These features overlap, so it helps to name the difference.

The key trait of a skill is progressive disclosure. The description sits in context so Claude knows the skill exists. The full body loads only when the skill is used. Long reference material costs almost nothing until you need it.¹

When does Claude load a skill?

By default, both you and Claude can invoke any skill.¹

You can type /skill-name to run it directly. Claude can also load it automatically when your request matches the description.¹ That auto-load behavior is why a specific description matters, which we cover below.

When to build a skill vs use the Shopify AI Toolkit plugin

Both exist. Pick based on what you are encoding.

The Shopify AI Toolkit connects Claude to Shopify’s docs, API schemas, and code validation, and can manage your store through the CLI’s execute capability.² It answers “what is the correct Shopify way to do this.”

A custom skill answers “what is our way to do this.” Build one when:

• You keep pasting the same section-scaffolding checklist into chat.¹
• A section of your CLAUDE.md has grown into a procedure rather than a fact.¹
• You have naming rules, schema patterns, or a review checklist specific to your store.

The two work together. Install the plugin for Shopify accuracy. Add a skill for your house style on top of it.

For a broader look at agent-based theme work, see our guide on multi-agent Shopify theme development.

SKILL.md structure and frontmatter

Every skill needs a SKILL.md file. The directory name becomes the command you type, and the description helps Claude decide when to load the skill automatically.¹

A minimal skill looks like this:

---
name: my-skill
description: What this skill does
---

## Instructions

The markdown body Claude follows when the skill runs.

The name and description are the two frontmatter fields that carry the weight.¹

Useful optional fields

The standard supports more frontmatter. A few that matter for Shopify work:¹

The allowed-tools field grants permission for the listed tools while the skill runs. It does not restrict which tools exist. Every tool stays callable, and your permission settings still govern the rest.¹

Folder layout: where skills live

Skills load from two main locations.¹

When skills share a name across levels, personal overrides project.¹

Commit project skills to version control so your whole team gets the same behavior.¹ A Shopify theme repo with a shared section-scaffolding skill means every developer generates sections the same way.

Bundling supporting files

The SKILL.md is required. Other files are optional and let you build more capable skills: templates for Claude to fill in, example outputs, scripts Claude can execute, or detailed reference docs.¹

A skill that scaffolds Shopify sections might look like this:

~/.claude/skills/shopify-section/
├── SKILL.md              # Required: when + how
├── references/
│   └── schema-rules.md   # Loaded on demand
├── templates/
│   └── section.liquid    # Starter template
└── scripts/
    └── validate.sh       # Claude can run this

Reference these files from your SKILL.md so Claude knows what they contain and when to load them.¹ Point script paths at ${CLAUDE_SKILL_DIR} so they resolve whether the skill is installed at the personal, project, or plugin level.¹

Worked example: a Shopify section scaffolder

Here is a full skill that scaffolds a Liquid section from a prompt and validates the result against your rules.

Step 1: Create the folder

mkdir -p ~/.claude/skills/shopify-section

Step 2: Write SKILL.md

Save this to ~/.claude/skills/shopify-section/SKILL.md:

---
name: shopify-section
description: Scaffold a new Shopify Liquid section with a schema block and validate it against our theme rules. Use when the user asks to create a section, add a section, or build a new section for a Shopify theme.
---

## Scaffold a Shopify section

When asked to create a section:

1. Create the file under `sections/` with a kebab-case name.
2. Write the Liquid markup, then a `{% schema %}` block at the end.
3. The schema must include a `name`, at least one setting, and a
   `presets` entry so the section is available in the theme editor.
4. Wrap the section in a container with a unique `id` scoped by
   `section.id` so styles do not leak.
5. Add settings for section padding (top and bottom) as `range` inputs.

## Validate before finishing

- Confirm every setting referenced in the markup exists in the schema.
- Confirm the schema is valid JSON.
- Confirm no inline styles use hard-coded colors. Pull colors from
  settings instead.

Report any rule the section breaks and fix it before returning.

The description is the load-bearing line. It names the exact actions a developer would ask for: “create a section,” “add a section,” “build a new section.” That phrasing is what Claude matches against.¹

Step 3: Invoke it

Ask something that matches the description, and Claude loads the skill automatically:¹

Create a hero section with a heading, subheading, and a background image setting.

Or run it directly:¹

/shopify-section

Claude reads the skill body, scaffolds the section under sections/, and runs your validation rules before it hands back the file.

If you also want the result checked against Shopify’s live schema rules rather than only your own, pair the skill with the AI Toolkit plugin. The plugin handles Shopify correctness; the skill handles your house style. For prompt patterns that pair well with this, see our guide on Claude prompts for Shopify.

Pitfalls to avoid in 2026

A few things trip people up when writing their first skill.

Vague descriptions

Claude decides whether to load a skill from its description.¹ “Helps with Shopify” is too broad and will either fire on everything or nothing.

Name the concrete actions instead: “create a section, add a section, build a new section.” Put the key use case first, because the listed text is capped at 1,536 characters and the start carries the most weight.¹

Bloated SKILL.md files

Keep SKILL.md under 500 lines. Move detailed reference material to separate files.¹

The body loads into context every time the skill runs, so a long file is a recurring cost. Push schema tables, long examples, and edge-case docs into references/ and link them.¹

Unreviewed tool permissions

For skills checked into a project’s .claude/skills/ directory, allowed-tools takes effect after you accept the workspace trust dialog.¹

A skill can grant itself broad tool access. Review project skills before trusting a repository, the same way you would review a permission rule.¹

Reaching for a skill when a plugin already exists

If Shopify’s toolkit already does the job, a custom skill is extra maintenance. Build one only when you are encoding conventions the plugin cannot know. For platform-specific setup on other editors, see our Shopify AI Toolkit Cursor setup guide.

Where Fudge fits

A skill makes Claude faster at writing Shopify code. It does not add the workflow real store changes need: drafts, previews, approvals, and rollback. Code lives in git; store state does not.

That gap is what Fudge fills. It is an AI-native Shopify store editor that generates on-brand drafts from a prompt, lets you preview and refine them, and publishes when you are ready. The people on your team who should not be writing Liquid or managing SKILL.md files can still ship changes. For the wider shift this fits into, see our take on AI-first Shopify development.

Quick reference

Summary

A Claude Code skill is a small, reusable folder that teaches Claude your Shopify conventions. Two fields do the work: a description that decides when the skill loads, and a body under 500 lines that tells Claude what to do.¹

Build a skill for your house style. Install the AI Toolkit plugin for Shopify accuracy. Use both together, and keep store publishing itself governed by drafts and previews rather than raw execution.

FAQ