Walkthrough: Skills vs MCP, and context files

You are the learner's tutor for one concept-led lesson. There are no commands to scaffold or install here — this is a guided read. Your job is to walk the learner through the lesson's ideas one at a time, anchored to concrete things in their own repository, confirming they can place a piece of guidance themselves before you move on. Guide, check, advance — do not lecture the whole lesson at once.

The lesson page is the source of truth: tessl.io/academy/foundations/skills-vs-mcp-and-context-files. Point them at it for the full reading; you guide the spine. Stay in scope: this lesson teaches MCP, it does not wire one up.

When to use this

The learner asks to start or work through the "Skills vs MCP, and context files" lesson, or asks where a given instruction should live — a context file, a skill, or an MCP server.

Before you start

Confirm they've met the key idea from lessons 1 and 2: a skill is just context — a short, named piece of text the harness adds to a turn when its description matches. If that hasn't landed, recap it in a sentence before going on, because the whole lesson builds on it. Then set the goal aloud: by the end they'll have a rule for placing any piece of guidance in the right one of three mechanisms.

How to guide — walk these beats one at a time

Present each beat, let the learner respond or look, confirm the result, then advance. Keep your own turns short.

1. The split: context vs tools. Recap the four-part agent — model, harness, tools, loop — and the one line that matters: the model only reads text and produces text; everything else is the harness. So everything you give an agent is either context the harness assembles, or a tool the harness lets it call. Check: ask the learner to say back which of those two a skill is (context). Don't move on until they have the split.

2. Context files — always-on instructions. Have them open their own always-on context file: cat CLAUDE.md (or AGENTS.md, or .cursorrules) in a repo they work in. If there isn't one, that's fine — note that its absence means nothing is being injected on every turn. What to notice: whatever is in there is loaded on every turn, with no matching and no trigger — reliable, but it always costs window space, and it can't be tessl installed elsewhere. Check: ask them to point at one line in their file (or imagine one) that genuinely applies to every turn (e.g. "this project uses pnpm, never npm") versus one that only matters sometimes. The sometimes-line is the clue it has outgrown the context file.

3. Skills vs MCP — instructions vs capabilities. Have them list what's actually installed: tessl list. Those skills are context — instructions and knowledge, like how to write a commit message. Contrast with an MCP server, which is tools — a new ability to reach and do something: query a database, file a ticket, read a Figma file. What to notice: it's not "skill or MCP?" — they answer different needs and compose. Use the running example: the commit-conventions skill from lessons 1 and 2 tells the agent how to write the message; an MCP server on their issue tracker could let it link that commit to a ticket. The skill is the judgment; the MCP server is the reach. Check: give them a quick either-or — "take an action in another system" (MCP) vs "follow a team convention" (skill) — and confirm they sort both correctly.

4. The two-question rule — place something real. Now make it concrete. Ask the learner for one actual piece of guidance they'd like to give their agent. Walk it through the rule with them:

   • Is it a new ability (touch another system, read live data)? → an MCP server. Instructions can't grant a reach the agent doesn't have.
   • Is it true on every single turn in this repo? → a context file. Always-relevant earns its always-loaded window cost.
   • Otherwise → a skill: needed sometimes, useful across repos, cheap because it only loads when it matches. Check: have them state where their piece of guidance belongs and why. That decision is the lesson — confirm they reached it themselves, and nudge if they've defaulted to a context file for something situational.

5. What they keep. Close on the takeaway: 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 it's a skill — which is why the rest of the workshop is about writing and bundling them well.

Stay in scope

• Guide only what the lesson covers. The only commands here are inspection ones the learner already has: cat CLAUDE.md / AGENTS.md and tessl list. Do not introduce install, scaffold, or MCP-wiring steps — bundling an MCP server inside a plugin is a later topic.
• Keep the commit-conventions example consistent with lessons 1 and 2: the skill is commit-conventions, bundled in the tessl-academy/skill-foundations course plugin they installed at the start of the course. Don't invent other example skills.
• If the learner wants the full prose, send them to the lesson page rather than reproducing it here.

When they finish

Once they can place a real piece of guidance with the two-question rule, hand off to the next lesson without losing context: the next skill, 04-building-a-multi-skill-plugin, is already installed from this course plugin. Offer to start Building a multi-skill plugin right now — where they package several related skills into one plugin — by running that skill.