No More Skill Issues (or Subagent Ones)
When there’s a chore you keep repeating with roughly the same input and output, and it takes several steps or is just boring enough that you dread it, you don’t want to re-explain the whole thing to an agent every time. You want to hand over the context once and then delegate. Claude Code gives you two ways to do that: skills and subagents. These are the tools we use at my office, so what I know about them comes from work rather than documentation.
They look the same on the surface. Both are a markdown file where you describe a task, lay out the steps, and set some rules. But the way they run is genuinely different, and once the mechanics click, it’s obvious why you’d reach for one over the other.
The mechanical differences
A subagent gets its own context window, completely separate from the main chat session. Whatever it thinks through or churns on during execution stays in that separate window, and the main session only ever sees the final result it hands back. A skill doesn’t get any of that. It runs inside the main session, so everything it does piles onto the same context you’re already chatting in.
That separation changes how you work while one is running. Kick off a subagent and you can keep talking in the main session while it does its thing in the background, then it reports back when it’s done. Roughly like calling an async function. A skill blocks you. If you want to keep chatting, you either wait for it to finish or open a new session.
Invocation differs too. Both can get summoned automatically based on what you asked Claude Code for, but only a skill gives you an explicit /{skill-name} you can type yourself. A subagent has no slash-command equivalent. You either let the main agent pick it or name it directly in plain language.
Subagents also give you a knob skills don’t. You can restrict which tools a subagent has access to and which model it runs on, while a skill just runs with whatever the current session already has available.
None of this adds up to a rule like “always use a subagent for X.” These are mechanics, and you match them against whatever you’re building.
The subagents I built for this site
There are four subagents in this repo: a content auditor and a content writer, each split into a blog version and a project version.
The auditor takes a draft, whatever rough notes I’ve pushed here, and checks it against the writing rules I’ve set for this site. It flags what’s off and reports back to the main agent. That context then goes to the writer subagent, which composes the real post from it.
The writer isn’t paraphrasing my draft. It’s writing the post properly, using the draft as source material. And the auditor isn’t only a first-draft gate. I can point it at something already published and get it checked again, which is what happened to this post.
Blog and project are split because they get graded on completely different things. A project post has to explain itself through situation, task, action, result, so the writer for that shapes everything around STAR. A blog post cares about SEO instead: title, slug, description, all of that. Rather than cram both into one subagent and hope it context-switches correctly, I kept them separate.
The blog cover generator skill
Before this skill existed, making a cover image for a post was a manual slog. I’d find a background photo on Unsplash, spin up this site’s local dev server pointed at an Astro page that overlays text on a background image, swap in the image I downloaded and the post’s title, take a screenshot (which auto-saves as a PNG), convert that PNG to webp with an online tool, then set the cover path in the post’s frontmatter.
The skill now handles all of that:
- I give it the Unsplash page link and the slug.
- It downloads the image and fills in the credit and link in the post’s frontmatter.
- It spins up the dev server and hits the cover route with the background and title as query params.
- It screenshots the result headlessly.
- It converts the PNG to webp, stepping quality down until the file’s under 100KB.
- It drops the final image into the blog’s images folder and cleans up after itself.
Picking the background photo is the one part I kept manual on purpose. Choosing a photo that suits the post is a judgment call, and I’d rather make it myself than hand it to a model and hope.
Why not just write a script for all this
A script only does what you explicitly coded it to do. Every variation has to be anticipated up front as a flag or an argument, and anything you didn’t think of either breaks loudly or does the wrong thing quietly. With a subagent or a skill, you describe what changed in plain language and it adjusts.
The cover generator shows this well. Hand it an Unsplash link where the og:image tag is missing or the dimensions come back weird, and a plain script would just fail. The skill can reason about it, find another way to get the asset, and keep going. Same with the auditor and writer pipeline. A script checking “writing rules” would need every rule spelled out as a regex or a condition, whereas the auditor subagent reads the draft, works out what’s wrong with the phrasing or the structure, and explains it back.
That’s the part I keep coming back to. Everyone in tech has an opinion about AI right now, and I’d rather spend the time learning how the pieces work before I add mine to the pile. Sitting down with skills and subagents for a few weekends taught me more than any of those takes did.
