Skill or agent? Pick the right one.
A skill is knowledge the agent loads. An agent is a worker you summon. Most teams confuse them, and most over-build agents when a skill would have done the work.
Different shape, different job.
A regular agent is a configured persona with its own tool budget, conversation context, and lifecycle. A skill is a folder of expertise that any agent can pick up and use. They're not competitors. They're different layers.
SKILL.md
A folder. A markdown file with YAML frontmatter. The agent loads it on demand when your request matches its description.
- Loaded by description match — lazy, not always on.
- Has no tools of its own; it tells the host agent what to do.
- Reusable across many agents and many conversations.
- Cheap to write, cheap to delete, cheap to version.
- Lives next to the code it serves.
Agent (.agent.md)
A configured role with its own identity, system prompt, tool allow-list, and (sometimes) its own model. You summon it to do a task; it runs and reports back.
- Always present when invoked — owns its own conversation.
- Has tools and constraints declared upfront.
- Can be a subagent: the main agent delegates work to it.
- Heavier to author; pays off when the role is reused.
- Often consumes skills to do its job.
The headline distinction: agents do things; skills tell whoever is doing the work how. A good agent is small and consumes many skills. A good skill is small and gets consumed by many agents.
Ask: do I need a worker, or just expertise?
If the answer involves a new persona, new tools, or a delegated subtask the main agent shouldn't handle directly — that's an agent. If the answer is "the main agent just needs to know how to do this kind of work" — that's a skill.
A few sharper tests:
- Does it need a constrained tool list different from the host agent's? → Agent.
- Does it run in its own conversation and report back a single result? → Agent (specifically a subagent).
- Is it just how to do a task the host agent is already capable of? → Skill.
- Does it bundle templates, examples, or scripts that get loaded only when needed? → Skill.
- Do you find yourself writing "act as a…" — meaning you want a different voice or scope? → Agent.
- Are you writing "when X, do Y, then Z" — a procedure for the current agent? → Skill.
Real cases, picked.
Use this as a sanity check before you scaffold anything. Most "I need an agent" requests turn out to be skills in disguise.
| You want… | Pick | Why |
|---|---|---|
| The agent to follow our internal release-notes format whenever it drafts release copy. | Skill | It's a workflow the host agent runs. No new tools, no new persona. Lives in release-notes/SKILL.md. |
| A read-only code explorer that searches the repo and returns a summary so the main chat doesn't get cluttered. | Agent | A subagent. Its own conversation, its own tool scope, returns one report. The main agent stays focused. |
| Convert a mood-board into HTML tokens using a procedure the team has refined. | Skill | Bundled knowledge + a procedure + sometimes a starter file. Exactly what skills are for. |
| A "code reviewer" that reads diffs against project standards and writes severity-graded findings. | Both | The reviewer is an agent. The standards it checks against are skills the agent loads. |
Tell the agent never to use --no-verify on git pushes. |
Neither — instructions | Always-on rule that binds to certain files. That's an .instructions.md, not a skill or agent. |
| A "PRD builder" persona that interviews you and produces a finished PRD. | Agent | It needs a persona, a conversational lifecycle, and a specific final artifact. Agent territory. |
The skills you'll write first.
If you're new and looking for a place to start, almost every team's first three skills fall into one of these shapes.
The style guide.
Your brand voice, your error-message tone, your naming conventions. Loads on customer-facing copy. Often the easiest first skill because the rules already exist on a wiki — you're just porting them.
The runbook.
A procedure for a recurring task: "how we write ADRs," "how we draft a security review," "what we check before merging a migration." Bundles templates the agent fills in.
The convention pack.
How your team does something the rest of the world does differently — your testing framework choice, your folder layout, your preferred CI patterns. Stops the agent from inventing a parallel universe.
Three parts, one takeaway.
Part 01 — a skill is a folder of conditional expertise. The agent only loads its body when your request matches the description in the frontmatter.
Part 02 — the agent finds your skill by reading descriptions, matching against your request, and loading the body. Write the description like a search query; write the body like a runbook; test in a loop.
Part 03 — skills carry knowledge; agents do work. Prefer a skill when the host agent can already do the task and just needs to know how. Reach for an agent when you need a new worker with its own tools and lifecycle.
You don't need to write a perfect skill to start. You need to write a small one, watch what the agent does with it, and iterate. Every skill in production started as a 30-line file that fired on the wrong prompts until its author tightened the description.