Parker Joseph
claudeai-agentsclaude-skillsagentic-workflows

Claude Skills vs Agents: The Practical Difference (With Real Examples)

Skills and agents solve different problems, but most explanations blur them together. Here's the distinction that actually matters, built from setups I run myself.

Why this confusion costs you time

I see "skill" and "agent" used as interchangeable words constantly, and it's not your fault if you're confused. Anthropic's own docs blur the line, and most blog posts just restate feature lists instead of explaining the actual split underneath. So people build a Skill when they needed an Agent, hit a wall, and assume Claude "can't do that" — when really they picked the wrong tool for the job.

By the end of this post, you'll know exactly which one to reach for given a specific problem. I'll walk through two systems I actually run for parkerjoai: a research pipeline and a content-review loop. Both use Skills and Agents, but for very different reasons.

What a Claude Skill actually is

A Skill is a folder. That's it structurally. Inside, you've got a SKILL.md file describing what the skill does and how to use it, plus optional scripts and reference docs. Claude doesn't load all of that into context up front — it uses something called progressive disclosure. It skims the short description first, and only pulls in the full instructions and files when your current task actually matches.

The important thing to understand: a Skill is a knowledge and capability package, not a running process. It has no memory between calls. It makes no decisions about when it should run — it sits there until something invokes it, then it does its one job and hands control back.

Concrete example: a markdown-to-newsletter Skill I use for parkerjoai. The SKILL.md says "use this when converting a draft markdown post into newsletter HTML." It includes formatting rules (heading levels, link styles, image handling) and a small Python script that fills a template. When I ask Claude to format a post for email, it loads that skill, runs the script, returns formatted HTML. No looping, no judgment calls about what to do next — just execution.

What a Claude Agent actually is

An Agent is the orchestration layer sitting above Skills and tools. It's a loop: take a goal, decide what to do next, check the result, decide again, repeat until the goal is met or a stopping condition kicks in. That loop is the whole difference. A Skill answers "how do I do this one thing." An Agent answers "what should I do next, and am I done yet."

The key primitives are tool calls (search, code execution, file access), subagents (spinning off a narrower task to another model instance), context management (deciding what to keep, summarize, or drop as the loop runs), and stopping conditions (a rubric met, a budget hit, a human check-in triggered).

The thing that matters most: an Agent carries state and makes decisions across multiple steps. A Skill does neither.

My research agent for parkerjoai is a good example. It takes a topic, searches for sources, reads and summarizes them, drafts an outline, writes a draft, then checks that draft against a quality rubric I wrote — tone, claim density, structure — before deciding whether to stop or revise again. It might call the markdown-to-newsletter Skill at the end, but the Skill isn't making any of those judgment calls. The agent is.

The core distinction: capability vs orchestration

Here's the whole thing in one line: a Skill answers "what do I know how to do, and how do I do it well." An Agent answers "what should happen next, in what order, and when do I stop."

Think of a Skill as a reference manual on a shelf — a really good one, with clear instructions for a specific job. It doesn't know when it's needed. It doesn't know what came before or what comes after. It just sits there until someone pulls it down and follows it.

An Agent is the person deciding which manual to pull, when to pull it, and whether the result is good enough to stop. That decision-making is the entire job. No manual, however well-written, can do that for itself.

Skills are static and reusable — the same markdown-to-newsletter skill works whether I'm formatting post one or post fifty. Agents are dynamic and goal-driven — the path changes every run based on what happens along the way. Neither one is "better." They're different layers doing different work.

Real example: the Skill I run for voice consistency

I have a skill called brand-voice-check. The SKILL.md describes the voice rules for parkerjoai: plain language, no buzzwords, write in "I/you," short sentences, name trade-offs instead of hyping. Underneath that description sits a short script that scans text for common violations — jargon words, passive-voice overuse, sentences over a certain length — and flags them with line numbers.

It's a Skill, not an Agent, because it does exactly one job and stops. It doesn't decide when a draft is ready for review. It doesn't revise anything. I (or an Agent) hand it text, it hands back a list of flags, done. No memory of the last draft it checked, no opinion on what should happen next.

The real limitation I hit: the first version of my SKILL.md description just said "checks writing style." Too vague — Claude often skipped loading it entirely because nothing in the task matched that phrasing closely enough. I rewrote it to "use this when reviewing a draft blog post or newsletter for brand voice violations — buzzwords, passive voice, missing I/you framing." Loading got reliable once the description got specific. Progressive disclosure only works if the short description actually describes the trigger, not just the topic.

Real example: the Agent that drafts and self-reviews

My content-drafting agent takes a topic, researches it, writes a draft, then loops back and calls brand-voice-check on its own output. If the check flags violations, the agent revises and runs the check again. It stops when the check passes clean or after 3 passes, whichever comes first.

That loop only works because the agent holds state the skill never could: which draft version it's on, what the last review flagged, and how many iterations have run. The skill has no idea any of that history exists — each call is a fresh, stateless check.

The failure mode I actually hit: early on, I didn't cap iterations. One rule in my voice guide was ambiguous enough that the agent kept "fixing" the same flagged sentence in ways that technically passed one check but tripped another, looping for way more passes than made sense and burning tokens for no real improvement. The fix wasn't a smarter prompt — I tried that first and it didn't help. The fix was a hard stop condition: max 3 passes, then hand back the best version with the remaining flags noted for me to fix manually. Stopping conditions aren't a nice-to-have. Without one, a loop has no reason to end.

How skills and agents actually work together

Here's the part most explainers skip: a skill doesn't do anything on its own. It just sits there until something matches its description and loads it. That "something" is almost always an agent. Agents are the orchestrators — they hold the goal, decide what step comes next, and pull in a skill mid-task when the task calls for it.

Without skills, an agent has to reinvent instructions every single run — rewriting voice rules, formatting logic, and alt-text conventions from scratch, burning context on things that don't change. My actual pipeline: the content-drafting agent writes, then calls brand-voice-check for voice, seo-format for headers and keyword placement, and image-alt-text for accessibility — but only the ones relevant to that run. A draft with no images never loads the alt-text skill. That's the whole point of keeping them separate.

When to build a skill vs when to build an agent

Here's the test I actually use. If the task is one well-defined operation you repeat often — formatting, a style check, converting data from one shape to another — build a skill. It's a single job with a clear stop point.

If the task needs multiple steps, decisions about what happens next, or a loop that runs until some condition is met, build an agent. Agents are for judgment calls; skills are for repeatable operations.

If you're not sure which one you need, default to building a skill first. It's cheaper to build, easier to test on its own — you can run it against ten sample inputs and check the output without any orchestration logic in the way — and if you later notice the same multi-step pattern happening around it, wrap it in an agent then. Going skill-first also means when the agent does misbehave, you already know the skill underneath it isn't the problem.

What didn't work (so you don't repeat it)

Three mistakes, named plainly. First, I overloaded one skill with voice checks, SEO rules, and formatting instructions all in one SKILL.md. Claude loaded it inconsistently because the description no longer matched any single trigger clearly. Splitting it into three narrow skills fixed that.

Second, I built the drafting agent before I'd tested brand-voice-check on its own. When output looked wrong, I couldn't tell if the skill's logic was broken or the agent's orchestration was. Testing skills in isolation first would've saved that debugging time.

Third, skipping stop conditions on the agent loop cost real API spend before I added the 3-pass cap. None of these are reasons to avoid skills or agents — they're just the cost of skipping the boring setup work.

Try this today

Pick one task you ask Claude to do over and over. Not a project — one operation. "Check if this email sounds too formal." "Format this into a comparison table." "Validate that this JSON has the required fields." Something you could describe in two sentences.

Write it as a single SKILL.md: a name, a one-line description of when to use it, and one worked example showing input and expected output. That's it. No branching logic, no loop.

Run it alone five or six times on real inputs you've got lying around. Don't wire it into an agent yet. If it's inconsistent at five runs, an agent on top won't fix that — it'll just hide where the problem is. Get the skill solid first. The agent can wait until you've got something worth orchestrating.