Skills as an Agent Tool Paradigm

The question this lesson answers

Lesson 07 mapped five tool paradigms — CLI, functions, APIs, MCP, A2A — and this lesson does not add a sixth. That's worth sitting with, because "skills" get pitched constantly as the next tool paradigm, the missing sixth row in that table. They aren't, and understanding why matters more than memorizing another row would. A skill is not a callable interface at all. It's markdown context the model reads in order to use a tool well. Calling it a sixth paradigm misunderstands the problem it's solving — it isn't competing with CLI or MCP for the same job, it's answering a completely different question: not "what can the model call" but "how does the model call the things it already has, well."

Two references before the new material: validating what you already built

Before the skills material, two pieces of reference work close out lessons 09 and 10's labs — this lesson supplies the test queries, not new implementation.

For the MCP venue server from lesson 09, two natural-language queries exercise the multi-tool discovery path: "Which Edinburgh venues fit 160 vegan guests, and how long until the booking deadline?" requires both search_venues and check_booking_window in the same turn. "Find the best venue and give me the full address and current availability" requires get_venue_details chained after a search.

For the A2A booking agent from lesson 10, three named test cases validate the server's business logic without changing a line of client code:

The observation worth carrying forward: the task ID, the polling loop, and the artifact extraction are identical across all three queries. Only server-side business logic differs. That's the A2A architecture from lesson 10 doing exactly what it promised — the client never needs to know how the server decided.

What skills actually are

Skills are structured markdown files describing a tool's behavior, constraints, and usage patterns, sitting between a system prompt and a tool schema.

Skills are not a protocol like MCP, and not a standard like A2A. They're an organizational pattern for giving an agent richer context about a capability it already has access to.

Skills are just text. The model reads them as context, and they work precisely because they carry richer guidance than a JSON schema alone can hold — but that richness costs tokens, which is the whole reason skills and schemas stay separate rather than merging into one bigger schema.

The six-question anatomy

A skill file earns its place by answering six questions the model otherwise has no way to know: what is this tool, when should it be used, how do you call it, what does success look like, what are the common failure modes, and what should you never do with it.

# web_search

Search the web for current information.

## When to use
- User asks about events after your training cutoff
- You need to verify a claim before acting on it

## When NOT to use
- User asks about well-known historical facts
- The answer is already in the conversation context

The misconception this lesson corrects

Here's the trap: engineers assume more description in the tool's JSON schema is always better, so they keep padding the description field until it reads like documentation. That's backwards, and the comparison table shows why directly.

The schema description is sent to the model on every single turn, whether or not the tool gets used. Padding it to twenty lines means paying that token cost every turn, forever. A skill file, by contrast, is loaded on demand — only when the task actually calls for that tool's deeper guidance. Conflate the two and you get one of two failures: bloat every turn's cost by cramming mastery-level detail into the always-present schema, or starve the model of the guidance it needs by keeping everything terse and hoping the schema alone is enough. Use the schema for selection, short and always present. Use the skill file for mastery, rich and loaded on demand.

That selection question gets harder as the tool count grows. This course's own testing puts the rough threshold at 20 tools reliably before selection quality starts to drop; past 100 or more, the model is picking the wrong tool often enough that the schema-only approach breaks down regardless of how well each individual description is written — treat both numbers as an observed working range, not a precise, universally measured cutoff. The response that holds up at that scale is a router: a small, fast model pre-selects the handful of tools actually relevant to the current turn, and only those get passed to the planner.

The planner never sees the other 95; it can't pick the wrong one out of a hundred if it was only ever shown five.

The file-location problem

A detail easy to miss and expensive to skip: an LLM has no concept of a filesystem. Dump a pile of skill files into context with no structural header, and the model has no way to know where any file lives, what its neighbors are, or how the project is organized — which risks the model hallucinating a file reference instead of asking for the real one. The fix is a structural header on every skill file naming its own path, its project, and its related skills, so the model can reason about what else might be relevant rather than guessing.

The real worked example is Claude Code's own file-reading skill — the one dispatched whenever a user uploads a file whose content isn't already in context. Its dispatch table names four concrete mappings:

This is not a theoretical pattern — it's the actual mechanism deciding, right now, whether a coding agent runs cat blindly on a file it can't read (wrong for most file types) or dispatches to the correct tool for that extension.

The paradigms are converging, not multiplying

Five paradigms across lessons 07-10, plus skills as the pattern that explains how to use them well — worth naming plainly that this map is already consolidating rather than growing a seventh or eighth entry. By 2026, MCP is already built into OpenAI's own Responses API, and A2A is already available inside Google's Vertex AI — two protocols that started as competing standards are now both just infrastructure options inside the major platforms. The working prediction worth carrying forward: by 2027, this stops being "which protocol" and just becomes "tools" — the paradigm question this lesson and lessons 07-10 spent five lessons answering carefully is exactly the question that gets to stop mattering once the platforms finish absorbing it.

A bridge, not a re-teaching

One more thing worth naming before this lesson closes, because it comes up in the same class discussion this material is drawn from: the distinction between a model hallucinating and a model being jailbroken looks similar from the outside but calls for different fixes — grounding with tools for the first, domain locking for the second. A real banking demo made this concrete when an escalation agent with no domain boundary happily invented a chocolate cake recipe. This lesson only bridges to that discussion; the full architectural fix — domain locking, and sizing a multi-model pipeline so one component's output doesn't silently break another's input budget — is lesson 12's exclusive ground, immediately next.