Every AI agent you use today — whether it’s Claude Code, GitHub Copilot, or Cursor Agent — starts each session essentially the same way: smart but clueless about your specific world. It doesn’t know your company’s deployment process. It doesn’t know that your team’s PRDs follow a specific format. It doesn’t know that when a Kubernetes deployment throws an ImagePullBackOff error, the first thing you should check is your registry auth role assignments.
So what do most people do? They stuff everything into system prompts. They bolt on MCP servers. They paste context into every chat. And then they wonder why the agent starts hallucinating or ignoring instructions halfway through a conversation.
There’s a growing backlash against this approach. AI users are finding that MCP servers are costly in both token usage and context pollution. Every MCP tool definition loaded into a session competes for the model’s attention, whether or not it’s relevant to the current task. Teams are looking for something more predictable, more cost-efficient, and more flexible.
The pattern emerging to solve this works exactly the way you’d onboard a high-IQ new hire.
Imagine you’re onboarding a brilliant new engineer. You have two approaches:
Approach A: Hand them a 500-page onboarding document on day one, plus 50 O’Reilly mini-books covering every process they might ever encounter. “Read all of this before you start. Memorize every word in all these books — you can’t take notes or look anything back up before you start.”
No reasonable manager would do this. The new hire would be overwhelmed, distracted, and most of what they memorized wouldn’t be relevant to their first task.
Approach B: Show them a bookshelf. Each book has a clear title and a one-line description on the spine. “Here’s everything we know. Don’t read any of it yet — just know it’s here. When you hit a problem, find the right book and read that one.”
Agent Skills are Approach B.
Agent Skills are plain Markdown files that encode business processes, domain-specific workflows, or specialized knowledge. They live in well-known directories (.copilot/skills/, .agent/skills/, .claude/skills/) and follow a simple structure:
-
YAML frontmatter at the top — a short title and description (the “book spine”) that must fit within strict character limits per the Agent Skills specification
-
Markdown body — the actual instructions, commands, scripts, and knowledge (the “book contents”)
As a Product Manager in the container space, I’ll use Azure Kubernetes Service (AKS) and Azure Container Registry (ACR) as a running example. Here’s what the frontmatter looks like for a skill that helps debug container image pull failures:
---
name: "AKS ImagePullBackOff Debugger"
description: "Use when a user encounters ImagePullBackOff errors in AKS clusters. Guides through ACR authentication checks, token expiration, Entra RBAC role assignments, Entra ABAC conditions, network policies, and image tag verification."
---The body of that Markdown file might contain:
-
Specific
kubectlcommands to run for diagnosis -
A decision tree for common root causes (expired tokens, wrong authorization assignments, wrong registry references, network policies)
-
References to local scripts packaged alongside the skill for automated checks
-
Instructions to pull, load, and use a local AKS MCP server for deeper cluster inspection
The key insight: when an agent session starts, it only reads the frontmatter of every skill file. That’s 100-200 tokens per skill — just the title and description. The agent now knows this skill exists and when to use it, without consuming any meaningful context.
Only when the agent encounters a relevant problem — say, a user asking about AKS image pull failures — does it read the full Markdown body. Just like a human reaching for the right book on the shelf.
You might be thinking: context windows are getting massive. Claude, Gemini, and Grok have all launched 1M+ token windows. If MCP server definitions only consume tens of thousands of tokens, does this optimization even matter?
Yes, and here’s why: context pollution isn’t about fitting — it’s about attention.
Large language models don’t treat every token in the context window equally. The more irrelevant information you pack in, the more the model’s attention gets diluted across things that don’t matter for the current task. Loading 50 MCP server definitions means the model is constantly “aware” of hundreds of tool signatures, parameter schemas, and usage descriptions that have nothing to do with what the user is asking about right now.
It’s the same reason a brilliant new hire can’t effectively work while simultaneously holding the contents of 50 reference manuals in their head. The information isn’t just taking up space — it’s actively competing for attention with the task at hand.
Agent Skills solve this by keeping the “bookshelf index” tiny (just frontmatter) and only loading full knowledge on demand.
A natural question: if Agent Skills are so great, do they replace MCP servers?
No. They co-exist, and a skill can actually leverage both depending on the complexity of the task.
Think of it as a spectrum. A skill’s Markdown body always starts with knowledge — the explanations, workflows, decision trees, and domain context the agent needs. But when the task requires more than just knowledge, a skill can escalate:
-
Knowledge only — The skill body contains instructions, decision trees, and commands for the agent to run directly. This covers most cases. The AKS debugging skill might walk the agent through running specific
kubectlcommands and interpreting the output. -
Knowledge + co-packaged scripts — For moderately heavy tasks, skills can reference bash or Python scripts that ship alongside the skill in its local directory. Instead of encoding a 50-step diagnostic procedure as prose, you package a local
diagnose-pull-errors.shscript that the skill tells the agent to execute. The script handles the heavy lifting; the skill tells the agent when to run it and how to interpret the results. -
Knowledge + MCP servers — For the heaviest tasks requiring rich API integrations or complex tool interfaces, a skill can instruct the agent to load a specific MCP server. The AKS debugging skill could tell the agent: “If the basic checks don’t resolve it, load the AKS MCP server and use its cluster inspection tools.” The skill provides the judgment of when to escalate and how to use the MCP tools for this specific workflow.
A single skill can use all three levels. The key point is that the skill is always the orchestrator — it encodes the decision-making about what approach to take and when to escalate. MCP servers and scripts are tools the skill can call on, not replacements for the skill itself.
The MCP specification has also been updated to support lazy loading of servers, which fits perfectly into this model. Skills help the agent decide which MCP server to load and when, and lazy loading means it doesn’t pay the context cost until it actually needs the tools.
There’s also a practical advantage for regulated environments: the co-packaged scripts at level 2 are distributed entirely locally. For enterprises with strict data sovereignty requirements — particularly common in regulated markets where AI endpoints and all AI dependencies must be deployed locally to the same network — this local-first distribution model for Agent Skills matters. The knowledge and automation live alongside the code, with no dependency on external services.
Vercel has curated a directory of community skills at skills.sh. You can browse popularly-installed skills, read their Markdown definitions, see the scripts packaged alongside them, and install them with npx skills add. Particularly worth studying:
-
The Anthropic doc-coauthoring skill — a great example of encoding a collaborative writing workflow
-
The Anthropic pdf skill — a good example of co-packaged local scripts distributed alongside the skill Markdown
-
The copywriting skill by Corey Haines — shows how to encode style preferences and content guidelines
-
The awesome-claude-skills repo (31k+ stars) — a curated collection of domain-specific skills across frameworks and tools
The most natural way to start writing skills is reactive: every time your AI agent makes a repeated mistake or produces output you don’t like, that’s a signal that domain knowledge is missing.
The workflow:
-
Notice the agent making an error or producing suboptimal output
-
Figure out what context or knowledge would have prevented the mistake
-
Use the skill-creator skill (itself a skill that guides the agent through creating new skills) to encode that knowledge as a Markdown file
-
The next time the agent encounters a similar situation, it will find and load your skill
Over time, you build up a personalized “bookshelf” of knowledge that makes your agent dramatically more effective at your specific work.
Skills are loaded from well-known directories depending on your agent:
-
.claude/skills/— Claude Code -
.copilot/skills/— GitHub Copilot -
.agent/skills/— Emerging general convention. Take note that the Agent Skills specification has not defined a well-known directory yet as of February 2026. You can symlink.claude/skills/and.copilot/skillsto.agent/skills.
You can also share skills across projects by placing them in global configuration directories, or distribute them as Git repos that teams can install.
Because skills are just files in your repo, they’re version-controlled alongside your code. They evolve with your codebase, get reviewed in pull requests, and have full git history. This is a quiet superpower compared to system prompts pasted into chat or MCP configurations managed outside your repository — skills are durable, auditable, and collaborative by default.
Here’s where it gets interesting.
Think about where business process knowledge lives today: internal wikis (GitHub wikis, Confluence, Notion), public documentation (Azure docs, AWS docs), runbooks, onboarding guides, incident playbooks. This knowledge is written for humans, scattered across dozens of platforms, and often stale.
Agent Skills are the beginning of encoding all of that as something agents can discover and use. Borrowing Palantir’s terminology, skills are becoming the digital twin of an enterprise’s operational knowledge — a structured, discoverable, version-controlled representation of “how we do things here.”
I can see a near future where companies have dedicated teams transforming domain knowledge into agent-discoverable formats. Not just skills files — this is likely the first of many standards — but the pattern is clear: encode knowledge in a way that agents can find it when they need it, without reading everything upfront.
And as agents accumulate more of these “digital bookshelves” — corporate handbooks, domain playbooks, team-specific workflows — they start to look less like tools you prompt and more like teammates you onboard. Multi-agent systems (like Claude Code’s sub-agents) can distribute specialized knowledge across coordinating agents, each pulling from different books on the shelf as needed.
We’re moving from “configure your AI tool” to “onboard your AI colleague.” Agent Skills are how that onboarding actually works.
If you’re new to skills, here’s a concrete first step: install the skill-creator skill and encode one thing your agent keeps getting wrong. You’ll be surprised how much better the next session goes.
Already building skills? I’d love to hear what domain knowledge you’ve encoded — reply or find me at johnsonshi.com.