How Claude Skills Actually Work

Transcript

The full word-for-word transcript of this episode. Plain text version

Marcus: When we talk about artificial intelligence, the imagery is always so grand. We picture vast neural networks, trillion parameter models.

Devon: Yeah, enormous server farms humming in the desert.

Marcus: Exactly. We imagine this inexorable sci-fi march towards artificial general intelligence. But then you look at the official guide for Anthropic's new skills feature for Claude, and you realise the latest leap in enterprise AI workflow is, well, it's a folder of markdown files.

Devon: It feels almost insulting. I mean, you expect a massive technological leap, and you are handed a digital filing cabinet. You read the marketing, and it implies this incredibly powerful new model capability or some sophisticated plugin architecture. But the reality is deceptively low-tech. It's essentially a zip file with a text document inside.

Marcus: That is the core of it, and that's exactly what we are taking a deep dive into: the official Anthropic guide to building skills for Claude. The fundamental premise here is to teach Claude a workflow once, so the user stops having to re-explain themselves in every single conversation. You package up your preferences, your business processes, your domain expertise into a simple folder, and Claude is supposed to just know what to do from then on.

Devon: And if you peek inside that folder, it requires exactly one file. Just one.

Marcus: Yeah.

Devon: It must be named skill.md, capitalised exactly like that, containing basic markdown text and some YAML front matter at the top.

Marcus: Spot on. You can include optional subfolders for scripts or standard operating procedure templates, but the absolute heart of this intelligent capability is a plain text file.

Devon: Which is brilliant in a way. The mechanism behind how this plain text file interacts with the AI is incredibly pragmatic, because it hinges entirely on a concept called progressive disclosure.

Marcus: Right, because otherwise the system would just buckle.

Devon: Precisely. If Claude had to hold every instruction for every single workflow in an entire company in its active memory all the time, the computing cost would be astronomical. The system would just collapse under its own weight.

Marcus: It's a very elegant way of saying, you know, do NOT overwhelm the system, and do NOT bankrupt the user.

Devon: Exactly. It's, it's like a bouncer at an exclusive club. Progressive disclosure operates on three strict levels.

Marcus: Okay.

Devon: The first level is that YAML front matter at the top of your skill.md file. That acts as the VIP list at the door.

Marcus: Right.

Devon: That tiny bit of text is always loaded into Claude's system prompt. It provides just enough information for the AI to know when a skill even applies to the user's request.

Marcus: And if the AI sees a match on that VIP list, it proceeds to level two.

Devon: Yes, level two is the main dance floor. The actual body of the skill.md file only loads into context if the task looks relevant based on that initial tripwire.

Marcus: Which is so clever.

Devon: It is. Then you have level three, which is the back VIP room. Any linked reference files within your folder, say a massive API documentation guide, they only load if Claude actively decides it needs to read them to complete this specific task.

Marcus: I see.

Devon: In fact, the official guide actually advises keeping the main skill.md body under 5,000 words, specifically to save tokens.

Marcus: And we should probably define tokens for a moment, especially if you're listening to this and managing a budget for an engineering team.

Devon: Yes, definitely.

Marcus: Simply put, tokens are the chunks of text a language model reads and generates. It is the fundamental currency of AI.

Devon: Right.

Marcus: It's how you are billed, and it's how the model's attention span is measured. Every unnecessary word you feed the AI is a token wasted and a fraction of a cent lost.

Devon: Which scales terribly.

Marcus: Exactly. Over an enterprise user base, that scales into massive overhead. So, by hiding the vast majority of the instructions behind this progressive disclosure mechanism, you are saving money and forcing the model to stay focused.

Devon: And the common story we always hear with AI is that we just need larger context windows, that we should be able to dump a million words into a prompt and let the machine sort it out.

Marcus: Yeah, just throw data at it.

Devon: Right. But the reality, as shown by this structure, is that careful, gated curation yields much better results. But to understand why this is happening now, we have to look at the broader effort to standardise AI plumbing.

Marcus: Yeah.

Devon: Because at the time of release, we have already seen a massive industry push to connect language models to external tools.

Marcus: You are referring to MCP, the Model Context Protocol?

Devon: I am.

Marcus: And look, if you have ever tried to get an LLM to reliably interact with different databases, you know what a nightmare that used to be.

Devon: Oh, it was incredibly fragmented. MCP essentially standardises the API calls.

Marcus: Right.

Devon: Instead of Claude having to learn the specific, messy, bespoke language of Notion, and then a completely different language for Asana, MCP acts as a universal translator.

Marcus: It's the standard plumbing.

Devon: Exactly. The plumbing that lets the AI securely talk to your company's data. And the guide uses a fantastic framing to differentiate that plumbing from this new skills feature. Think of the connectivity layer, MCP, as the kitchen.

Marcus: I absolutely love this analogy because it perfectly illustrates the user frustration we've been seeing for the last year.

Devon: Yeah.

Marcus: MCP provides the professional kitchen. It gives Claude access to the tools, the raw ingredients, the ovens. That is the plumbing. But a kitchen on its own does not make a meal.

Devon: No, it doesn't.

Marcus: Skills are the knowledge layer. Skills are the recipe. They provide the step-by-step instructions on how to cook.

Devon: It so clearly delineates the problem, doesn't it? Because users will connect an MCP server, giving Claude access to their entire corporate database, and then they sit down, stare at the chat box and think, well, what do I do now?

Marcus: Right.

Devon: And when the AI inevitably fumbles a complex, multi-step data retrieval process, the user blames the connector. They blame the kitchen for not knowing how to bake a cake, when in reality, nobody ever handed the chef a recipe.

Marcus: That is the pivotal shift here, my favourite part of this whole deep dive. The common story is that skills are a powerful new AI capability that makes the model smarter.

Devon: Yes.

Marcus: But the reality is that their success depends entirely on dull human discipline. The value of this tool has almost nothing to do with the language model's artificial intelligence, and everything to do with boring, meticulous human knowledge management.

Devon: It's an exercise in scoping, triggering, and testing.

Marcus: Completely. And that human discipline is entirely focused on one tiny, unforgiving bottleneck in this whole system. That YAML front matter you mentioned earlier, the VIP list.

Devon: Oh, the constraints on this are incredibly tight.

Marcus: It's the absolute lynchpin. The description field in that front matter is capped at 1,024 characters.

Devon: Which is nothing.

Marcus: Nothing. Within that tiny limit, you must explicitly state exactly what the skill does and exactly when the AI should use it. You cannot use XML tags to structure it.

Devon: Right.

Marcus: You cannot write a sprawling paragraph. That single, brief field determines whether the model will even look at your carefully crafted markdown file.

Devon: The absurdity of this character tax is quite something, because if you write a vague description, I mean, the guide gives the example of writing "helps with projects", if you do that, you under-trigger the system. The AI simply ignores your folder entirely. You've given it a recipe book with a blank cover, and it never bothers to open it.

Marcus: And under-triggering means you have to go back into the file and painstakingly add specific trigger phrases, things like "use this to create sprint tasks" or "trigger when asked for design specs". But then you face the immediate opposite problem. If you over-trigger, your skill starts aggressively hijacking completely unrelated conversations.

Devon: Which is infuriating for the user.

Marcus: Oh, totally. And the guide's proposed solution to over-triggering is to literally write negative instructions into those precious 1,024 characters.

Devon: Yeah.

Marcus: You have to spend your limited character count writing things like "do NOT use for simple data exploration". You are paying a literal tax in characters just to tell the AI when to leave you alone.

Devon: It is a remarkably finicky balancing act, but there is a wonderful debugging trick the guide suggests for exactly this problem.

Marcus: Oh, I love this bit.

Devon: If you want to know why your skill is acting up or why it keeps ignoring your requests, the best way to debug it is literally just to open a chat and ask Claude, "When would you use this skill?"

Marcus: Yes.

Devon: And Claude will simply quote your own 1,024-character description right back to you.

Marcus: It forces you to hear exactly how inadequate your own instructions are.

Devon: Exactly.

Marcus: It's like reading your own poorly drafted, passive-aggressive email out loud to see where the tone went wrong.

Devon: That's exactly what it is. But look, digging into this instruction manual raises a massive red flag, and honestly, it is the most significant admission hidden in the entire Anthropic guide.

Marcus: You are talking about the quiet concession regarding language models themselves.

Devon: Yes.

Marcus: Yes.

Devon: We are talking about a system built by one of the premier artificial intelligence companies in the world.

Marcus: Yeah.

Devon: Yet, the guide actively recommends that for anything critical, anything that requires perfect, strict validation, you should not trust the language model's reading comprehension.

Marcus: It's a huge admission. The exact phrasing in the guide is striking. It says, "Code is deterministic; language interpretation isn't."

Devon: Right there in black and white.

Marcus: Yeah. So, for critical validations, Anthropic recommends bundling actual executable scripts, like a Python script or bash script, inside the skills folder, rather than relying on written prose instructions in the markdown file.

Devon: This is a horrifying and amusing edge of this entire deep dive. The company building a state-of-the-art large language model is quietly admitting that language instructions are ultimately unreliable when precision truly matters. All the marketing sells you on limitless intelligence, on natural language programming being the future of work. But the technical substance of their own guide demands that you don't actually trust the language model to follow a strict set of rules.

Marcus: They are saying it out loud. They are saying, yes, Claude is brilliant at drafting an email or synthesising a 50-page market report, but if you need to verify that a project name is non-empty and the start date is not in the past, well, please, for the love of God, just write a Python script.

Devon: That tension, you know, between the promise of conversational AI and the rigid reality of software engineering, it spills right over into the cultural and organisational fallout of this tool.

Marcus: Absolutely.

Devon: Because we have to talk about what happens when these folders are actually deployed at scale inside a business.

Marcus: Well, in December 2025, they shipped a feature for workspace-wide deployment.

Devon: Right.

Marcus: Admins can now push a skill across a whole enterprise workspace with automatic updates, meaning one person's idiosyncratic, tidy little folder sitting on their desktop silently becomes the entire company's default workflow.

Devon: This is the nightmare scenario for IT governance. I mean, who audits that folder?

Marcus: Nobody, usually.

Devon: Imagine you have Dave in accounting. Dave writes a highly specific, very clever skill.md for generating the Q3 financial reports, complete with negative prompts and custom reference files. It works beautifully for Dave.

Marcus: Right.

Devon: Then, Dave leaves the company. Who inherits Dave's markdown file? Who is auditing the YAML triggers? More importantly, who actually pays for a workflow nobody remembers writing, which is now silently governing how the AI interacts with the company's most sensitive financial database?

Marcus: It's a massive blind spot. It essentially turns every power user in the company into an undocumented software developer. They are building infrastructure, but they are treating it like a personal notes file.

Devon: And it turns the company's central nervous system into a series of zipped folders sitting on an admin panel, completely opaque to the people actually doing the work.

Marcus: It does. But if we look at it from the software vendor's perspective, this architecture completely reshapes the industry.

Devon: Oh, completely.

Marcus: If you are a company providing an MCP connector, say, you sell an enterprise issue tracking software, shipping a pre-built skill alongside your connector gives you a massive competitive edge.

Devon: Because you are providing the recipe along with the kitchen.

Marcus: Exactly. You are preemptively solving the customer's confusion. Think about the user journey before skills. A user installs your integration, tries to use the AI to create a ticket, the AI hallucinates the required fields, and the user gets frustrated.

Devon: Right.

Marcus: What do they do? They open a Zendesk ticket with your support team complaining that your integration is broken.

Devon: And customer support is incredibly expensive.

Marcus: Extremely. But if a vendor provides a rigorously tested skills folder, they quietly shift the burden of customer support completely out of ticketing systems. The workflow is embedded directly into the AI's prompt via that skill.md file.

Devon: That's clever.

Marcus: If the user makes a mistake, the AI reads the recipe and guides the user back on track. The support ticket never happens.

Devon: Which is brilliant for the vendor's bottom line. It obscures the actual mechanics of the software behind a veil of AI magic. But, you know, you look at those vendor pitches, and they rely heavily on the metrics Anthropic published in this guide.

Marcus: They do.

Devon: And I look at those same measurement targets, and my immediate reaction is deep scepticism. I think we have a genuine disagreement here on how this guide frames its own success.

Marcus: You are looking at the success metrics they suggest for building a good skill.

Devon: I am looking at them, and I am raising an eyebrow. The guide suggests targets for developers like triggering on 90% of relevant user queries and achieving zero failed API calls per workflow.

Marcus: Right.

Devon: They provide a work example in the documentation claiming a massive drop in friction, going from 15 messages and 12,000 tokens to accomplish a task down to just two questions and 6,000 tokens when using a skill.

Marcus: Well, those are undeniably impressive numbers for any engineering team looking to adopt this.

Devon: But they are completely unconfirmed numbers. The guide itself openly admits that these are aspirational targets, and that measuring them involves, and I quote directly from the text, "an element of vibes-based assessment."

Marcus: Vibes-based assessment.

Devon: Let me repeat, that for anyone building enterprise software, vibes-based assessment. The actual measurement tooling is apparently still being built. To me, measured but partly by vibes is the exact hype pattern this show exists to dismantle.

Marcus: I see your point. You cannot pitch a tool for rigorous knowledge management and then tell developers to measure its success on vibes. Look, I hear you on the vibes, but let's be fair for a second. We need to look at what this is replacing. Prior to this standardisation, how were organisations actually using AI?

Devon: Fair question.

Marcus: They were flying totally blind. Enterprise AI was the Wild West. Every single prompt was a roll of the dice, highly dependent on the mood of the user and the phrasing of the request.

Devon: That's true.

Marcus: Even if these targets are aspirational, even if the assessment is rough and ready right now, having a baseline target of 90% accuracy or attempting to halve your token count is vastly better than the total chaos of unstructured prompting.

Devon: Better than chaos, sure. I will grant you that.

Marcus: Yeah.

Devon: But when you position a feature as enterprise-grade infrastructure, which they absolutely are doing by pushing that December 2025 workspace-wide deployment feature, you cannot rely on vibes to know if your database API calls are quietly failing in the background.

Marcus: Well, the guide is attempting to bridge the gap between deterministic software and probabilistic language models. The metrics have to start somewhere, even if the initial measuring stick is a bit crude.

Devon: We see that exact same pattern with the claims they make about portability, though. Agent Skills is published as an open standard, and it is meant to be entirely portable. The pitch to developers is that you write a skill.md folder once, and it works identically across claude.ai in the browser, Claude Code in the terminal, and via the API.

Marcus: And it reportedly does, provided the environment supports it.

Devon: If that holds up being the operative phrase there. The guide itself lists some very real caveats that undermine the marketing. Portability is highly conditional.

Marcus: Right.

Devon: It depends entirely on the host environment supporting the necessary dependencies. Some skills are built specifically for one platform's unique capabilities. And if you want to use skills via the API for automated backend pipelines, the documentation notes it actually requires the Code Execution Tool, which at the time of release is still in beta.

Marcus: Ah.

Devon: So, it is an open standard in theory, but in practice, you are navigating a maze of environment-specific constraints.

Marcus: I will concede the caveats on portability. If you are building a complex workflow that requires executing local bash scripts to comb through a hard drive, naturally, that is not going to seamlessly run in a standard web browser environment without some heavy lifting on the backend. The standard isn't magic. It still obeys the laws of computing.

Devon: Exactly. And treating it like magic is where companies are going to get into trouble.

Marcus: Let us bring this all together. We have looked at the low-tech mechanism of markdown files, the incredibly tight constraints of progressive disclosure, the vendor economics deflecting support tickets, and the somewhat aspirational vibes-based metrics.

Devon: Quite a list.

Marcus: If we strip away the marketing hype about autonomous agents, what is the concrete takeaway for the listener?

Devon: The takeaway is that we urgently need to reframe how we think about this tool. Claude's skills are not a magical upgrade to the AI's core intelligence. They are highly effective, heavily constrained knowledge management artefacts disguised as AI features.

Marcus: Yeah.

Devon: It is a forced exercise in standardising human thought.

Marcus: The common story we tell ourselves is that we are waiting for AI to become smart enough to do our jobs. But the reality exposed by this Anthropic guide is that the AI is actually waiting for us to be disciplined enough to explain our jobs.

Devon: And that requires a level of clarity and documentation that most organisations simply do not possess.

Marcus: No, they don't.

Devon: We rely entirely on implicit knowledge. We rely on the fact that Dave in accounting just knows how to format the Q3 report based on five years of institutional memory. We don't write it down.

Marcus: Which leaves us with a final thought to mull over, one that stretches beyond just managing our current workloads. If the future of work requires us to explicitly document our jobs into rigid markdown files so an AI can execute them, our core value becomes mere curation. We become editors of the recipe rather than the chefs in the kitchen. If that happens, what happens to the entry-level workers? How does the next generation learn the nuances of a profession if the foundational repetitive tasks they traditionally learn by doing are entirely hidden inside a zip file they never open?

Devon: It's a scary thought. If the AI does all the cooking, nobody learns how to chop an onion, and a perfectly formatted YAML file isn't going to teach them.

Marcus: A sobering thought to leave on.