Skills, Tools, Specs and Workflows - Which One is Which

When building with AI agents, you quickly encounter several overlapping concepts: tools, skills, specs, workflows. They're related but distinct. Here's how I think about them.

Tools

Tools are the fundamental capabilities an AI agent has. Reading files. Editing files. Running bash commands. Fetching URLs. These are built into the agent itself.

MCP tools are extensions — third-party capabilities that plug into the agent through the Model Context Protocol. Someone writes an MCP server to give the agent access to their API or service.

Skills

Skills are domain-specific expertise — knowledge and instructions for getting good at particular activities. Think of them like skills you'd have yourself: things you've learnt over time, through experience. They follow progressive disclosure. You don't dump everything upfront. Instead, you reveal detail as needed, keeping the initial context light. Skills can bundle scripts or reference materials. These aren't static — you improve them as you learn what works.

Specs

Specs are the contract. They define what should be done, what success looks like, and why you made certain decisions. They're not instructions on how to do the work — that's what skills are for — but the criteria against which you judge the result. When you're arguing about whether something's finished, you're arguing about the spec.

Workflows

Workflows are procedures — checklists of steps to complete. They reference skills (the know-how) and specs (the definition of done). When you invoke a workflow, you're saying "do these things, in this order, using this expertise, to meet that standard." Think of them as recipes that call out both ingredients (skills) and what the dish should taste like (specs).

Skills are baked into the workflow definition itself — they're the expertise the workflow uses. Specs, on the other hand, are invoked when you kick off the workflow — they define what you're trying to achieve this time.

Why it matters

Understanding these distinctions helps you build more reliable AI agent systems. Tools are the agent's hands. Skills teach it what to do with those hands. Specs define success. Workflows orchestrate the work.

Get them straight, and you'll stop wondering why your agent keeps doing the wrong thing.