Claude Code Subagents

TL;DR: Solis’s sol-builder subagent, an optional theme-check-fixer example, and the day-to-day workflow that ties skills, commands, and subagents together.

Shopify’s Official AI Toolkit ships skills, which turn on automatically. Claude Code Custom Commands covers commands, which you trigger yourself by typing /. This page covers the third piece, subagents, and shows how all three fit together in a normal day of work, using the pieces Solis actually has plus one optional example.

What a subagent actually is

A subagent is a specialized Claude Code assistant that runs in its own separate conversation. It has its own instructions and its own set of tools, instead of running inline in your main conversation.

Claude hands a task to a subagent in one of two ways. It can do this automatically, when the task matches what the subagent’s description says it does, or you can ask for it by name.

The subagent does the work, which might mean reading a dozen files, running commands, and going back and forth on fixes. Then it returns only a summary to your main conversation. All the messy in-between output, like file contents, command logs, and failed attempts, stays inside the subagent’s own conversation instead of cluttering yours.

That’s the specific problem a subagent solves that a command doesn’t. A command, like /theme-check-fix, runs its instructions inline, in your main conversation. That’s good for a quick, interactive session where you want to watch each step. A subagent does the same kind of job but keeps it separate, which matters once the job is noisy (many issues, many files), or when it’s something you want handled automatically without typing a command at all.

Claude Code also comes with several built-in subagents, like Explore, Plan, and general-purpose. Claude uses these automatically for research and multi-step tasks. You don’t need to set them up. They’re just always available.

Solis’s real subagent: `sol-builder`

Solis has one project subagent today: sol-builder, dispatched by /figma-to-feature to build one approved phase of a theme feature at a time — see Claude Code Hooks & the Feature Pipeline for that one, since it only makes sense alongside the hooks and command it’s dispatched from.

The rest of this page also walks through theme-check-fixer, a second subagent this handbook offers as an optional template, not something Solis has adopted. It’s a useful second example precisely because it’s a simpler, standalone case: it does exactly what its name says, running shopify theme check and fixing every issue it reports, with none of sol-builder’s hook/plan machinery around it. If you want it, download it:

Download theme-check-fixer.md into .claude/agents/ at your repo root:

.claude/
  agents/
    theme-check-fixer.md   →  runs automatically, or via "use the theme-check-fixer agent"
  commands/
    theme-check-fix.md     →  /theme-check-fix (same job, runs inline)

---
name: theme-check-fixer
description: Runs `shopify theme check` and fixes every reported offense, one at a time, consistent with this repo's AGENTS.md conventions. Use after generating or editing Liquid/JSON theme files, before opening a PR, or whenever asked to "clean up lint" / "fix theme check offenses."
tools: Read, Edit, Bash(shopify theme check:*)
model: inherit
---

You are a Shopify theme linting specialist for this repository...
[full process: run check → fix each offense per AGENTS.md conventions →
log each fix → re-run to confirm clean → ask instead of guessing on
anything that implies a product decision → report the fix log]

If you did adopt it, here’s why you’d want both this subagent and a /theme-check-fix command, instead of picking just one:

	`/theme-check-fix` (command)	`theme-check-fixer` (subagent)
Runs in	Your main conversation	Its own separate conversation
Triggered by	Typing `/theme-check-fix`	Automatically (Claude notices a matching task) or by name (“use the theme-check-fixer agent”)
Best for	A quick, interactive pass you want to watch	A noisy job (many issues) at the end of a longer task — this is exactly why `/figma-to-feature`’s real Step 4 hands its static check off separately rather than resolving each issue inline
Tool access	Whatever your session already has	Limited to exactly `Read, Edit, Bash(shopify theme check:*)`. It can’t touch anything else, even if your session has broader access

Both read AGENTS.md automatically. Subagents load the project’s CLAUDE.md/AGENTS.md and git status at startup, the same way your main session does. So neither one needs Solis’s rules repeated in its own instructions. They just point to the file.

The day-to-day workflow, put together

Here’s how a typical task actually flows with the pieces Solis actually has:

You describe what you want. Maybe you say “build a testimonials section from this Figma frame,” or you just start editing a .liquid file directly.
Skills turn on automatically, with no action from you. If the AI Toolkit is installed (see Shopify’s Official AI Toolkit), shopify-liquid notices theme-related work and runs its search-then-check process in the background. You don’t invoke a skill, it just applies on its own. Solis’s own sol-shopify-review skill works the same way for a finished component, if you ask for it by name.
You reach for a command when the process is a known, repeatable sequence. /figma-to-feature <url> runs the full plan → build → review → test loop as one coordinated process, instead of you retyping each stage.
A subagent picks up the noisy part. /figma-to-feature dispatches sol-builder to build one approved phase at a time, in its own conversation, instead of filling up your main conversation with every file it reads and edits. You get back a short report, not a wall of in-between output.
You review the result, like any other AI-generated change. See GitHub Workflow for how. None of skills, commands, or subagents replace review. They just get you to something reviewable faster, with less repetitive typing.

The short version: skills are automatic and about correctness (don’t guess at Liquid syntax, or at this theme’s own conventions). Commands are manual and about repeatability (don’t retype the same multi-step prompt). Subagents are automatic-or-named and about keeping your conversation clean (don’t let a noisy sub-task clutter your main conversation, and let it run with deliberately limited tools).

Deciding which mechanism to build next

Not every recurring need calls for a subagent, and not every subagent candidate should just be a command instead. A rough guide:

If the thing you keep doing is…	Reach for…
A specific fact or pattern you want applied automatically, without asking every time (e.g. “always check the current filter syntax before writing Liquid”)	A skill. Shopify’s own `shopify-liquid` skill (via the AI Toolkit) covers generic Liquid correctness. Solis also has one project skill of its own, `sol-shopify-review` (checks a finished component against `AGENTS.md`’s rules), so “we don’t write our own skills” isn’t quite right anymore, see the note below
A multi-step process you run the same way every time, and want to trigger on purpose	A command (`.claude/commands/<name>.md`). See Claude Code Custom Commands for the full guide
A sub-task that’s noisy (many files, many rounds of edits) or that should run with limited tool access, whether or not you ask for it directly	A subagent (`.claude/agents/<name>.md`). See this page
A rule that must be enforced no matter what, not just followed when the AI remembers to	A hook (`.claude/hooks/<name>.sh`). See Claude Code Hooks & the Feature Pipeline
Something so simple it’s not worth automating	Neither. A one-off prompt is fine

Could we write our own skill instead of a subagent?

Technically, yes, and Solis already has one: sol-shopify-review is exactly this, a .claude/skills/sol-shopify-review/SKILL.md folder that checks a just-finished section, block, or snippet against AGENTS.md’s conventions and runs validate_theme, run on demand by name rather than dispatched automatically mid-build. Claude Code’s commands and skills are the same underlying mechanism now (see the note in Claude Code Custom Commands). A full .claude/skills/<name>/SKILL.md folder, instead of a single-file command, makes sense when the job needs supporting files, like bundled scripts, templates, or reference data, or when you want it to turn on automatically rather than by typing /command.

For “run theme check and fix everything” specifically (the illustrative theme-check-fixer example above), a subagent fits better than a skill. The real win is keeping the conversation clean (no offense-by-offense noise in your main conversation) and limiting its tools (this job should only read, edit, and run theme check, nothing else). Those are things a subagent gives you that a skill doesn’t.

If a need is more about “check this specific, already-finished thing against our rules, on demand,” a project skill like sol-shopify-review fits better than a subagent.

Writing your own subagent

Notice a task that’s either noisy (it would fill your main conversation with output you won’t reference again), or one you keep asking Claude to do “as a specific persona with limited tools.”
Ask Claude directly to write it. You can say something like “create a project subagent in .claude/agents/ that does X, restrict it to tools Y, use model Z,” or write the file by hand following the format above.
Give it a specific description. This is what Claude compares against a task to decide whether to hand it off automatically. A vague description, like “helps with theme stuff,” won’t trigger reliably. That’s the same lesson as writing a specific rule in AGENTS.md.
Limit tools to only what the job needs. This is what actually enforces the restriction, not just a note about intent.
Test it. Describe a task that should trigger it, and confirm Claude actually hands it off instead of doing the work inline. Also test asking for it by name, to confirm that works too.
Commit .claude/agents/<name>.md to the repo so the whole team gets it. It’s the same idea as commands and AGENTS.md itself.

Do / Don’t

✅ Do	❌ Don’t
Limit a subagent’s `tools` to exactly what its job needs. The benefit of keeping it separate only pays off if the subagent genuinely can’t do more than intended.	Writing a subagent for a job that’s actually simple and not noisy. That’s what a command (or just asking directly) is for. A subagent’s separation is only worth it when there’s real noise to keep out of the way.
Write the `description` field the way you’d write a specific `AGENTS.md` rule. Make it concrete enough that Claude reliably matches the right task to it, not a vague summary.	Leaving `tools` unset when a subagent should be limited. An unset `tools` field inherits everything your main session can do, which defeats the point of limiting a linting-only subagent to read, edit, and theme-check.
Keep a subagent focused on one job, the same discipline as commands. A subagent that tries to do five unrelated things is harder to trust and harder to fix.	A vague `description` that Claude can’t reliably match against, so it either never hands off the task, or hands off the wrong ones.
Commit project subagents (`.claude/agents/`) to the repo. Save `~/.claude/agents/` for genuinely personal habits that apply across projects.	Duplicating a command’s job as a subagent, or the other way around, without a reason. Keep both only when the separation and tool-limiting trade-off genuinely matters for that job, as it does for `theme-check-fixer`.

Key takeaways

Subagent = its own conversation, limited tools, and hands off automatically or by name. Command = same kind of job, runs inline, manual /trigger. Skill = automatic, about correctness (Shopify’s shopify-liquid, or Solis’s own sol-shopify-review).
.claude/agents/<name>.md (project, committed) or ~/.claude/agents/<name>.md (personal). Frontmatter: name, description (both required), tools, model (both optional, and leaving tools unset means it inherits everything).
Solis’s one real subagent: sol-builder (see Claude Code Hooks & the Feature Pipeline). theme-check-fixer (download) is this page’s optional, illustrative second example, not something Solis has adopted.
Both sol-builder and theme-check-fixer load AGENTS.md/CLAUDE.md automatically at startup, so there’s no need to repeat Solis’s rules in a subagent’s own instructions.