Microsoft's Agent-Skill Advice Is Brutal and Correct: Stop Shipping Textbooks to the Context Window
Microsoft’s best agent advice this week is not a new model, a bigger context window, or another “autonomous” demo that quietly assumes the happy path. It is Waldek Mastykarz telling developers to stop overloading agent skills. Brutal, correct, and apparently still necessary: most teams do not need to ship a textbook into the context window. They need a measured cheat sheet for the few things the model actually gets wrong.
The post’s central claim is simple. Modern coding models already know a lot: default imports, common CRUD patterns, standard auth flows, SDK conventions, public docs, Stack Overflow answers, GitHub examples, and blog-post-shaped usage patterns. If a model already generates correct code for an API 90% of the time, the useful skill is not a full documentation mirror. It is the missing 10%: recent breaking changes, product-specific quirks, unusual authentication rules, configuration footguns, migration hazards, or patterns that are not well represented in training data.
That sounds like common sense until you inspect real agent stacks. Teams see a bad answer, conclude the model “needs more context,” and respond by dumping API references, architecture notes, style guides, long examples, and version histories into skills. Sometimes the result improves an edge case. Often it just taxes every request. The agent spends context budget reading things it already knew while the actual repository, test output, and user intent compete for space. Congratulations: you made the model slower, more expensive, and not necessarily better.
Baseline first, skill second
Microsoft’s recommended process is the part teams should pin to the wall. Define the scenarios. Run them without the skill, using the same model, harness, and prompts. Score the outcomes. Identify the failures. Build only for those gaps. Measure again. Account for token count. The post explicitly warns that “lift at 3x the tokens is a net loss.” That line should be printed on every agent-platform roadmap.
The baseline step is non-negotiable because without it, skill design is guessing. Worse, it is usually biased toward the documentation the team is proud of rather than the failure modes users hit. A product team that just published a beautiful API guide will be tempted to stuff it into the skill. A measured team asks the more annoying question: what does the model already do correctly without our help? If the answer is “most of it,” the skill should be short.
The related Microsoft agent-experience posts make the token math concrete. A harness assembles context before the model answers: system prompts, environment details, workspace files, tool descriptions, conversation history, instruction files, and the user prompt. Another Microsoft post estimates that a single MCP server with eight tools might add roughly 2,000 tokens of tool descriptions; five MCP servers can add 10,000 tokens before the user has asked anything. That is not free real estate. It is pre-spent attention.
This matters even before billing enters the room. Context is a scarce resource for quality. Every overloaded skill competes with the files the agent needs to edit, the failing test output it should read, the project instructions it should follow, and the prior turns that explain the task. After usage-based pricing and Copilot AI Credits enter the room, oversized skills become a cost problem too. A 3,000-token skill that helps one migration edge case while riding along on every normal completion is not documentation. It is drag with a nicer filename.
Lean skills are also safer skills
There is a security and governance argument here that deserves more attention. Skills are executable-adjacent guidance. They shape what the agent thinks tools are for, which examples it copies, which APIs it reaches for, and what it treats as recommended behavior. The larger and messier the skill, the more places stale instructions, overbroad permissions, or confusing tool-selection language can hide.
Microsoft’s related post on extension composition warns about vocabulary collisions, guidance conflicts, and resource competition. That is exactly what happens when every team ships its own giant “AI-ready” bundle. One skill says use the new SDK. Another old example imports the deprecated package. A repo-level AGENTS.md says do not add dependencies. An MCP server description suggests a tool that requires broad credentials. The model is left to reconcile policy soup and then everyone acts surprised when the answer is weird.
Shorter skills are easier to audit. They are easier to compose. They are easier to test against baseline scenarios. They are also easier to delete, which is underrated. Agent guidance should have owners and removal criteria. If a skill existed to teach a model about a breaking change and the model now handles that change reliably without the skill, remove it. If an example no longer reflects the current SDK, remove it. If a paragraph does not produce measurable lift, remove it. Treat context like a dependency, not a scrapbook.
The practical workflow for engineering teams is not complicated, but it does require discipline. Start by inventorying every skill, MCP server, tool description, repository instruction, and default prompt your agents see. Count tokens. Run a small scenario suite with no extensions, then with each extension, then with the full stack. Measure success rate, number of turns, latency, manual repair, and token usage. Keep the extensions that create net lift. Split broad skills into scenario-specific ones. Put high-risk or rarely used guidance behind explicit activation instead of loading it by default.
For product teams publishing agent integrations, this changes the definition of “AI-ready.” It is not enough to provide your docs in Markdown and call it a skill. The better artifact is a tiny, tested layer that teaches the model what public training data does not: the new auth flow, the non-obvious config, the deprecated pattern to avoid, the deployment constraint, the one error users mis-handle. If your model baseline already succeeds, your skill should mostly stay out of the way. Silence is a feature when context is scarce.
The deeper industry point is that agent work is moving from prompt folklore to systems engineering. Skills should be evaluated like features: baseline, intervention, measurement, regression tests, cost accounting, and rollback. “More context” is not a strategy. It is a habit, and often a bad one. The teams that win with coding agents will not be the ones with the thickest instruction bundles. They will be the ones that know exactly which extra tokens earn their keep.
Microsoft’s advice lands because it pushes against the current incentive. Everyone wants to ship an agent extension. Fewer teams want to prove the extension improves outcomes after token cost and composition effects. But that proof is the work. Agent skills should be regression-tested cheat sheets for known model failures, not documentation dumps wearing an “AI-ready” badge. The context window is not a warehouse. Stop treating it like one.
Sources: Microsoft Developer Blog, How AI coding agents actually use your technology, When your agent extensions fight each other