Claude Code Skills: Teaching Your AI Coding Agent Your Stack

A coding agent that has read your whole repo still doesn't know your team's rules. It doesn't know that you deploy with a specific four-step script, that every API endpoint returns errors in one shape, or that the one database migration command must run exactly as written. So you tell it, then you tell it again next session, because the agent starts each conversation fresh. Claude Code skills are the fix for that loop: a way to teach an AI coding agent a procedure once and have it applied every time it is relevant, without re-explaining your stack on every task. This is a practitioner's guide to what skills are, how the SKILL.md model and progressive disclosure work, how skills differ from MCP and plain tools, and how to author ones that hold up when a team depends on them. It is the close-up on a practice we sketch in our guide to shipping with AI: giving the agent your stack instead of just a prompt.

What Claude Code skills are

A Claude Code skill is a folder with a single file named SKILL.md inside it. That file holds two things: a short description of what the skill is for, in YAML at the top, and a set of instructions in plain Markdown below it. That is the whole format. You write the procedure you keep repeating, the agent adds it to its toolkit, and it applies that procedure when your request calls for it, or you run it directly by typing / and the skill's name.

Anthropic introduced Agent Skills in October 2025 and defines them plainly: "Skills are folders that include instructions, scripts, and resources that Claude can load when needed." The Claude Code docs give the practical trigger for making one: "Create a skill when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact." If you have copied the same deploy steps or review checklist into a conversation for the third time, that is a skill waiting to be written.

Here's the thing to hold onto: a skill is procedural knowledge, not a feature you install. You're not extending the model's raw capability; you're handing it the know-how it would otherwise lack about your code, your conventions, your deploy process. The model is already a strong general engineer. A skill makes it a competent engineer on your particular codebase. And because skills follow the Agent Skills open standard, the same format runs across the Claude apps and the API too, so what you encode once isn't locked to the terminal.

A skill is not a new capability you bolt onto the model. It is the onboarding doc you would have written for a new hire, except the agent reads it the instant the work calls for it and never the rest of the time.

One note that trips people up: custom slash commands and skills are now the same mechanism. Anthropic merged them, so .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both give you a /deploy command and work identically. Old command files keep working; the skill form just does more.

How Claude Code skills work

A skill has to answer one engineering question: how do you give an agent a large library of procedures without stuffing all of them into its context window on every turn? Context is finite and shared. Your conversation, the open files, and every available tool compete for the same space, and a window crammed with reference material the agent doesn't need is a window that performs worse on the work it does.

The answer is progressive disclosure, and it works in three levels. Anthropic's engineering team describes it directly: the agent loads almost nothing up front and pulls in detail only as a task demands it.

1. Metadata, always loaded. At startup the agent pre-loads the name and description of every installed skill into its system prompt. That is a few dozen tokens per skill, just enough for the agent to know what exists and when each one applies.
2. The body, loaded on a match. When your request matches a skill's description, the agent reads that skill's full SKILL.md into context. Only then does the procedure itself arrive.
3. Bundled files, loaded as needed. A skill can reference other files in its folder, a long API reference, an example collection, a script. Those are the third level. The agent navigates to them only when the task actually reaches that material.

The payoff is that a skill can be large where it needs to be and still cost almost nothing until it fires. A skill bundling a thousand lines of API reference adds only its one-line description to the startup budget; the reference sits on disk, consuming zero context tokens until a task opens it. As the Claude Code docs put it, "a skill's body loads only when it's used, so long reference material costs almost nothing until you need it." That is the advantage skills hold over a project memory file, which loads in full every session whether the work needs it or not.

The mechanics underneath are unglamorous, and that's the point: it's a filesystem. The agent reads a skill's metadata at startup, opens SKILL.md and bundled files with ordinary reads when the moment comes, and runs bundled scripts without loading their source, so only a script's output costs tokens. There's no special runtime to learn. A skill is a directory you can read, diff, and check into git like any other part of your codebase, which is most of why it fits an engineering workflow at all.

What a SKILL.md actually contains

The frontmatter is short. The only field Anthropic recommends is description, because that's what the agent reads to decide when to use the skill. name is optional and defaults to the folder name. A handful of other fields tune behavior: allowed-tools pre-approves specific tools so the agent doesn't stop to ask permission while the skill runs, and disable-model-invocation: true keeps the agent from triggering the skill on its own, which you want for anything with side effects, like a deploy or a commit, where you decide the timing, not the model. The body below the frontmatter is just the instructions, and the guidance is to keep it tight; once a skill loads, its content stays in context for the rest of the session, so every line is a recurring cost.

A minimal example, the shape of the thing, is a few lines:

---
name: api-conventions
description: API design patterns for this codebase. Use when writing or reviewing API endpoints.
---

When writing API endpoints:
- Use RESTful naming conventions
- Return errors in our standard `{ error, code }` shape
- Validate every request body before handling it

That is a complete, working skill. The agent now applies those conventions whenever you ask it to touch an endpoint, because the description told it when to pay attention.

Skills vs MCP vs tools: where each fits

People new to this stack collapse three different things into one, and the result is confusion about what to reach for. Skills, the Model Context Protocol, and tools sit at distinct layers, and they are most useful understood as complementary rather than competing.

A tool is a single capability the agent can invoke: read a file, run a shell command, call a function. Tools are how the agent acts on the world. On their own they are atomic; the agent decides which to call and with what arguments, one at a time. We go deeper on the role of tools in our explainer on how AI agents work, where the tool layer is the part of an agent that touches anything outside its own text.

MCP is the integration layer that exposes tools and data to the agent in a standard way. The Model Context Protocol is an open standard Anthropic released in November 2024, described by its own docs as "an open-source standard for connecting AI applications to external systems," with the analogy that it is "a USB-C port for AI applications." When you want your coding agent to reach your real database, your issue tracker, or an internal service, you connect it through an MCP server. MCP is the wiring; it gives the agent access.

A skill is the procedural knowledge that tells the agent how to do a task with whatever tools and data it can reach. It is not a connection and not a single action. It is the workflow: the steps, the order, the conventions, the things-to-check. Anthropic frames the relationship explicitly, that "Skills can complement Model Context Protocol (MCP) servers by teaching agents more complex workflows that involve external tools and software." The two layers are designed to stack. A skill can even name a specific MCP tool to call as part of its procedure, using the server-qualified form like BigQuery:bigquery_schema, so the know-how and the connection meet in one place.

Laid side by side, the three answer different questions:

The decision rule that holds up: if the agent cannot reach something, you need a connection, which is MCP or a tool. If it can reach it but does the task the wrong way, you need knowledge, which is a skill. Reaching for a skill to solve a connection problem, or an MCP server to solve a how-to problem, is the most common way teams get this stack wrong. Connecting a coding agent to the systems around your code is the broader discipline our AI integration services handle end to end; skills are the layer that teaches the agent to use those connections well.

Authoring a skill: what makes a good one

The gap between a skill that helps and one that gets ignored is almost entirely in two places: the description, and the discipline to keep the body short. Anthropic's skill-authoring best practices are worth reading in full, but the load-bearing parts are few.

The description is the whole ballgame for discovery. It is the only thing the agent sees when deciding whether a skill applies. Write it in the third person ("Generates commit messages by analyzing git diffs"), not the first or second ("I can help you..."), because the text is injected into the system prompt and a shifting point of view confuses the match. State both halves, what the skill does and when to use it, with the concrete words a person would actually type when they need it. "Helps with documents" triggers on nothing useful; "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDFs, forms, or document extraction" triggers on exactly the right requests. There is a budget, too: in Claude Code the combined description is capped at 1,536 characters in the skill listing, so put the key use case first.

Concise beats comprehensive in the body. Anthropic's guidance is blunt that "the context window is a public good," and the default assumption should be that the model is already smart. Only add what it does not already know. A skill that explains what a PDF is wastes tokens; one that says "use pdfplumber, here is the call" earns them. Keep the SKILL.md body under about 500 lines, and when it grows past that, split the depth into separate files the body links to, one level deep so the agent reads each referenced file whole instead of previewing a nested one with a head and acting on half of it.

Match the freedom to the stakes. Some tasks have many valid paths and the agent should be trusted to choose; a code review is an open field, so give general direction. Some are a narrow bridge with cliffs on both sides, like a migration that must run in an exact sequence, so give the exact command and say not to deviate: "Run exactly this script. Do not add flags." Specificity should rise with fragility, not with your anxiety.

Then actually test it. A skill triggering is not the same as a skill working. Collect a few realistic prompts, run each in a fresh session with the skill available and again with it disabled, and compare; a fresh session matters, because leftover context from writing the skill papers over gaps in the instructions. If it fires when it should not, make the description more specific; if it stays silent when it should run, add the trigger words a user would say. That loop is where a mediocre skill becomes a reliable one, and it is the kind of close, evidence-based iteration that separates senior pairing with AI from hopeful prompting.

Skills on a team: encoding your stack's conventions

A personal skill saves you from repeating yourself. A project skill saves your whole team from re-deciding the same things, and that's where the practice earns its keep for an engineering org. The difference is just where the folder lives.

A skill at ~/.claude/skills/<name>/SKILL.md is personal; it follows you across every project. A skill checked into a repository at .claude/skills/<name>/SKILL.md belongs to that project, and it ships to everyone who clones the repo. That second case changes how a team works. Your deploy procedure, your error-handling shape, your "always exclude test accounts in analytics queries" rule, your migration command, all of it can live in version control next to the code, reviewed in pull requests like any other change, and applied identically by every engineer's agent and every CI agent that touches the repo. The conventions stop living in senior engineers' heads and start living in a file the agent reads.

Anthropic's recommended way to build a skill is telling here: do a task once with the agent the normal way, notice the context and rules you kept supplying by hand, then ask the agent to capture that pattern as a skill. The knowledge you would have explained to a new hire in their first week becomes a skill the agent applies from its first task. And because skills are scoped, a monorepo can give each package its own .claude/skills/ that activates only when the agent works in that package, so front-end conventions and data-pipeline conventions do not bleed into each other.

There is a real control surface once a skill can do things. disable-model-invocation: true means only a human can run the skill, which you want on anything with side effects so the agent never decides on its own that the code "looks ready" and deploys it. And allowed-tools in a project skill takes effect only after a developer accepts the workspace trust dialog, the same gate as any project permission, which is the right instinct: a skill checked into a repo can grant the agent broad access, so you review project skills before you trust the repository, exactly as you would a new dependency.

Encoding your conventions as skills is, in the end, a story about scale. It is how a senior team's judgment reaches past the people who hold it, and a large part of what "AI-native" means in practice rather than in a tagline. It is also the craft we look for in the engineers we bring on: the discipline to make a process repeatable instead of heroic. If that is how you think about building, the roles we are hiring for are the place to start, and the bet we are compounding is exactly this, that teams who turn their hardest-won conventions into machine-applied skills compound a real edge over teams who keep re-explaining them.

Where Claude Code skills help, and where they don't

This cluster exists to separate capability from hype, so here's the honest line on skills: they're genuinely useful for a specific shape of problem, and the wrong tool for several others.

Skills help most when the same multi-step procedure or body of conventions comes up repeatedly and you want it applied consistently without re-explaining it. A deploy sequence, a code-review checklist, a set of API conventions, a way of writing commit messages, a domain's data schema and query rules: these are procedural, recurring, and worth encoding once. The recurrence is the signal. A skill pays for the effort of writing it the third or fourth time you would have explained the same thing by hand.

The broader context is that this kind of agentic coding is moving from novelty toward normal, but unevenly. The 2025 Stack Overflow Developer Survey found 84% of developers now use or plan to use AI tools, up from 76% the year before, while trust in their output fell to 29%, down from 40%. Among the narrower group already running agentic workflows, 70% reported that agents reduced the time they spent on specific tasks. Skills are aimed squarely at that trust gap: a procedure encoded once, reviewed by a human, and applied the same way every time is more predictable than re-prompting from scratch and hoping the agent infers your conventions. Consistency is the product.

But skills do not fix everything that looks like a job for them, and three limits matter.

A skill is guidance, not a guarantee. The agent chooses to follow a skill the way it chooses to follow any instruction; it's steered, not constrained. The Claude Code docs are candid that a skill can stop influencing behavior mid-session as the model favors other approaches, and the suggested fix is to strengthen the description or "use hooks to enforce behavior deterministically." So when you need a hard rule, not a strong suggestion, like blocking a commit that fails a check rather than reminding the agent to run it, a deterministic hook or a CI gate is the correct tool. Skills inform; hooks and gates enforce. Don't ask a skill to be a guardrail it was never designed to be.

Single facts belong in memory, not a skill. If the thing you want the agent to know is one durable fact, "our staging URL is X," "we use pnpm, not npm," that's a line in your project's CLAUDE.md, not a whole skill. Skills are for procedures that load on demand; facts you always want present belong in always-loaded memory. Using a skill for a one-liner is overhead with no payoff.

One-offs are not worth encoding. The cost of a skill is writing and maintaining it, so for a task you will do exactly once, just tell the agent in the conversation. The skill earns its keep through repetition. And a stale skill is worse than none, because the agent will confidently apply an out-of-date procedure, so a skill you no longer follow should be deleted, not left to rot.

None of this is a knock on skills. It is the boundary that makes them useful: they are the right home for your team's recurring, procedural know-how, and the wrong home for hard constraints, single facts, and one-time work. Get the boundary right and a skill becomes the most durable way to make an AI coding agent fluent in your particular stack. That fluency, knowing which procedures to encode and which guarantees to enforce elsewhere, is the everyday craft of the modern AI software engineer, and it is the work we do on every build.