Lesson 3 — Skills vs MCP, and context files

You've installed a skill and watched it fire, and you've written one of your own. Along the way you met the idea that does most of the work in this whole curriculum: a skill is just context, a short, named piece of text the harness adds to a turn when its description matches the work in front of the agent. It doesn't change the model. It only changes what the model is looking at.

Once that lands, an obvious question follows. If a skill is just context, it can't be the only way to add context, so what are the others, and when should you reach for each? This lesson is the map. No new commands; by the end you'll be able to look at any piece of guidance you want to give an agent and know whether it belongs in a context file, a skill, or an MCP server.

What you'll work out

• Why CLAUDE.md and AGENTS.md exist, and what they're genuinely good at.
• The real difference between a skill and an MCP server, and why it's not an either/or.
• A two-question rule for placing any new piece of guidance in the right one of the three.

A quick recap: where context lives

The differences all come down to one picture, so it's worth thirty seconds on it. A coding agent is four parts stacked together: the model (text in, text out: Claude, GPT, Gemini), the harness (the program around it, like Claude Code, Cursor, Codex, or the Tessl Agent, which reads files, runs tools, and decides what context to inject), the tools the harness exposes, and the loop that drives the whole thing turn by turn.

The part that matters here: the model doesn't do anything on its own. Everything you give an agent is either context the harness assembles for the model to read, or a tool the harness lets the model call. That single split, context versus tools, is what separates the three mechanisms below.

The mental model. The model reads text and produces text. Everything else is the harness. So "how do I steer the agent?" is really "what does the harness put in front of the model, and what can it let the model reach?"

Context files: always-on instructions

Before skills existed, the simplest way to steer an agent was a file it reads every time: CLAUDE.md for Claude Code, AGENTS.md for Codex and others, .cursorrules for Cursor. The harness loads it into the context window on every turn, automatically, with no decision about whether it's relevant.

That always-on behavior is the whole trade-off.

• No matching, no trigger. A skill only loads when its description matches the request. A context file is always present, so it can never fail to fire. For instructions that apply to every turn in a repo ("this project uses pnpm, never npm", "all dates are UTC"), that reliability is exactly what you want.
• It always costs window space. Always-on means always paid for. Every line competes with the actual task for the model's attention. A 500-line CLAUDE.md is 500 lines loaded whether you're fixing a typo or refactoring a module.
• It's per-repo, not portable. A context file lives in one repository and travels with it. A skill is packaged in a plugin and installed anywhere. You can't tessl install someone's CLAUDE.md rule the way you install a skill.

The mental model. A context file is for what's true all the time, here. A skill is for what's needed sometimes, anywhere. Put project-wide constants in the context file; put situational, reusable procedures in skills.

The mistake teams make is dumping everything into CLAUDE.md because it's easy, until the file is so large it crowds out the task and the agent starts ignoring half of it. When an instruction only matters sometimes, it has earned its way out of the context file and into a skill.

Skills vs MCP: instructions vs capabilities

Context files and skills are both context: text the harness reads. MCP is the one that's different, and it's the comparison people get wrong most often. They ask whether a skill and an MCP server do the same job. They don't; they touch different parts of that four-part agent.

• A skill is context. It's instructions and knowledge the harness injects into the turn when the description matches: how to write a commit message, what your team's review bar is. It doesn't give the agent any new ability to act; it shapes how the agent uses the abilities it already has.
• An MCP server is tools. The Model Context Protocol is a standard way to expose tools and data to an agent: query a database, file a ticket, read a Figma file. It extends what the agent can reach and do, not how it's instructed to behave.

So the question isn't "skill or MCP?" They answer different needs:

They compose. The commit-conventions skill from the first two lessons tells the agent how to write the message; an MCP server connected to your issue tracker could let it link that commit to a ticket. The skill is the judgment; the MCP server is the reach.

The mental model. Skills change what the agent knows and how it behaves. MCP changes what the agent can touch. Most real setups use both.

(We're teaching MCP here, not wiring one up; bundling an MCP server inside a Tessl plugin is a later topic. For now, knowing which problems it solves is enough to place it correctly.)

Choosing among the three

You now have three ways to give a coding agent what it needs. They're not rivals (most projects use all three), but each has a job it's best at. When you're deciding where a piece of guidance belongs, ask two questions: how often is it relevant, and is it instructions or capability?

A quick way to place something:

1. Is it a new ability, like touching another system or reading live data? That's an MCP server. Instructions can't give the agent a reach it doesn't have.
2. Is it true on every single turn in this repo? That's a context file. Always-relevant means always-loaded earns its window cost.
3. Otherwise it's a skill: needed sometimes, useful across repos, and cheap because it only loads when it matches. This is where most reusable guidance belongs.

The default. When in doubt, write a skill. A context file that should have been a skill bloats every turn; an action that should have been an MCP server can't be faked with instructions. But situational guidance, the large middle ground, is what skills are for, and unlike a context file it travels to every repo and teammate that installs it.

Take commit-conventions: a procedure, needed only when you're committing, and useful in every repo you work in. Not every-turn (so not a context file), not a new capability (so not MCP). A skill, exactly. That's why the first two lessons built it as one.

What you keep

You walk away with a rule you can apply to anything you want an agent to do better: ask how often is this relevant and is it instructions or capability, and the answer points at a context file, a skill, or an MCP server. Most of the time the answer is a skill, which is exactly why the rest of this workshop is about writing and bundling them well. Next, you'll take several related skills and package them into a single plugin.