Your Agents Keep Making the Same Wrong Assumption. The Fix Is a Markdown File.

Why Does the Same Agent Make the Same Wrong Assumption Every Sprint?

Ask an engineering leader what changed about AI coding in the last year and you will usually get an adoption number back. The adoption question is settled. JetBrains' 2026 global developer survey of more than 15,000 professional developers found that between May and July 2026, 90% of professional developers were using AI coding agents at work at least weekly, and 68% were using them daily. There is no interesting debate left about whether teams use these tools.

The interesting number is the other one. Anthropic's 2026 Agentic Coding Trends Report describes what it calls the delegation gap: developers now use AI in roughly 60% of their work, but report being able to fully delegate only 0 to 20% of tasks. Sixty percent involvement, twenty percent autonomy at the very best. Everything in that spread is cost, and it is a specific kind of cost: the review, the correction, the second attempt, and the conversation where a senior engineer explains for the fourth time a rule the agent had no way of knowing.

It is tempting to read that gap as a capability problem that the next model release will close. Spend a week watching what actually goes wrong and a different picture emerges. The failures are rarely reasoning failures. They are context failures of a very mundane kind. The agent writes a perfectly correct migration and puts it in the wrong directory because your team moved migrations two years ago. It calls the internal billing service directly, which works in staging and is forbidden in production for reasons that were decided in an architecture review in 2023 and written down nowhere. It generates a config file that is valid, idiomatic and rejected by your deploy pipeline because your pipeline has one non-standard requirement nobody has documented since the person who added it left.

None of that is in a foundation model's weights, because none of it is public. Most of it is not in your documentation either, or it is, in a twelve-page Confluence article written for a human reader who can skim, infer, and ask a colleague. A March 2026 paper on arXiv names this the Institutional Impedance Mismatch, and makes an observation worth sitting with: three classes of knowledge consumer face the same structural deficit under different constraints, with AI agents bounded by a finite context window, newly onboarded engineers bounded by limited absorptive capacity, and cross-team engineers bounded by the time pressure of operating in an unfamiliar codebase.

That reframing is the useful part. If your agents keep making the same wrong assumption and your new hires keep asking the same question in their second week, those are not two problems. They are one problem with two symptoms, and the bottleneck is knowledge architecture rather than model capability. Which is good news, because knowledge architecture is something an engineering team can actually fix.

What Changed When a Markdown File Became a Standard

In December 2025, Agent Skills was released as an open specification: a format for packaging procedural knowledge so that any agent can load it. The unit is a folder. Inside it sits a SKILL.md file with YAML frontmatter carrying a required name and description, a markdown body containing the instructions, and optional scripts and data assets alongside it. That is the whole format. There is no runtime, no service to call, no SDK to adopt, and no registry you are required to publish to. The reference repository is a public collection of these folders, which tells you most of what you need to know about the ambition of the design.

The adoption curve was unusual even by 2026 standards. Within 48 hours the format was wired into VS Code and into OpenAI's ChatGPT and Codex CLI, and by March 2026 some 32 tools from competing vendors, including Gemini CLI, JetBrains' Junie, AWS's Kiro and Block's Goose, were reading the same SKILL.md files out of the same directory structure. Cursor, Windsurf and GitHub Copilot landed support in the same window. It has since moved out of command-line tools and into enterprise SDKs: Microsoft's Agent Framework shipped Agent Skills support for Python, with a .NET release following.

The reason a boring format won is that it is boring. Every previous attempt to make organisational knowledge machine-readable required you to adopt a platform: a vector database, a hosted knowledge service, a proprietary plugin manifest, a vendor's idea of an ontology. Each one created a second source of truth that immediately began drifting from the first. SKILL.md is plain text in your repository. It is diffable, so a change to a deployment procedure shows up in a pull request. It is reviewable, so the senior engineer who knows the rule can approve the wording of the rule. It is versioned with the code it describes, so when the code changes the skill changes in the same commit or the reviewer notices that it did not.

It is worth being precise about how this relates to the other protocol layer, because teams conflate them constantly. MCP gives an agent reach: the ability to call your systems, read your database, open your ticketing tool. Skills give an agent procedure: what to do with that reach, in what order, subject to which constraints. An agent with tools and no procedure is a very fast junior developer with production credentials, which is close to the worst configuration available. We wrote about the reach half of this problem in our piece on MCP and the protocol layer; skills are the half that determines whether the reach is useful or dangerous.

The Context Economics That Separate a Skill From Documentation

The first objection every engineering leader raises is fair: this is documentation with extra ceremony, and we already have documentation nobody reads. The answer is progressive disclosure, and it is an economic argument rather than an aesthetic one.

A skill loads in three stages. The name and one-line description of every installed skill stay resident in the agent's context at all times, which is what lets the agent know the capability exists. The full instruction body loads only when the agent decides the skill is relevant to the task in front of it. Scripts and data assets load only at the moment they are executed. The practical effect is that an agent can be aware of a hundred procedures while paying the context cost of one.

The numbers make the case better than the description does. In a worked enterprise scenario, the startup descriptions for all ten installed skills consumed 773 tokens, while eagerly loading the complete instruction bodies would have required roughly 13,900 tokens, and loading the bodies together with their associated scripts roughly 65,900. That is close to two orders of magnitude between the naive approach and the designed one, and it is the difference between a skill library that scales to an organisation and one that stops being usable at about fifteen entries.

Token cost is the smaller half of the argument. The larger half is attention. Every token of instruction sitting in a context window competes with the actual task for the model's attention, and a context stuffed with a hundred procedures the agent does not need is measurably worse than a context with three it does. This is why compression of the skills themselves has become its own small research area: one optimisation framework reports a 48% mean compression rate for skill descriptions and a 39% mean reduction in body tokens without changing behaviour.

There is a deeper contract difference here that matters more than the token arithmetic. A retrieval system hands an agent a document and asks it to interpret. A skill hands an agent a specification and asks it to execute: what the procedure accomplishes, which tools to invoke, which constraints to respect, and where to go next. Interpretation is where agents invent things. Removing the interpretation step from the parts of your workflow that have exactly one correct answer is, in practice, most of what closing the delegation gap looks like.

Does It Actually Work? The One Deployment With Published Numbers

Almost everything written about skills so far is vendor material or enthusiasm. There is one enterprise deployment with numbers attached, and it is worth reading honestly rather than selectively.

A deployment at Yahoo covering 87 modular skills across multiple business units surveyed 67 engineers anonymously and reported an average of 2.6 hours per week saved per engineer in task-relevant work, with a Net Promoter Score of +35 and large to very large effect sizes across all four perceived-experience drivers measured. As a headline that is respectable rather than spectacular, which is itself a point in its favour.

Two findings underneath the headline are more interesting than the headline. First, no significant differences were detected across business units or tenure levels, which means the benefit was not concentrated in the power users who would have adopted anything. Second, the deployment measured an acceleration in new-hire ramp-up. That is the Institutional Impedance Mismatch showing up in the data: the same artifact that stopped agents guessing also stopped humans guessing, because both were failing for the same reason.

The caveats deserve equal billing, because a business case built on 2.6 hours a week will not survive contact with a CFO. The paper's authors name them explicitly: self-report bias, a single-organisation design, a small sample, and no objective productivity instrumentation. Nobody should be modelling headcount off that figure. What the deployment does establish is the mechanism, and the mechanism is what you can reason about in your own organisation: when procedural knowledge becomes loadable, correction cycles stop repeating.

The structural recommendation from the same work is the part most teams skip. The proposed schema has seven components: intent, procedure, tool bindings, organisational metadata, governance constraints, continuation paths, and validators. Most teams that start writing skills produce the first three and stop. Continuation paths are what turn a pile of skills into something navigable, where finishing one procedure tells the agent which procedure comes next. Validators are deterministic scripts that check whether the output meets an organisational standard without a human in the loop, and they are the single highest-leverage component in the list. The deployment's own operational learnings were mundane and predictable: validator coverage was uneven, staleness detection had to be built, and the biggest ceiling on adoption was competing documentation surfaces, which is to say the wiki nobody deleted.

Skills Are Packages, Which Means You Just Acquired a Supply Chain

The moment a format becomes portable, a marketplace appears. The moment a marketplace appears, so does the attack, and this one arrived faster than most.

An audit of all 2,857 skills on ClawHub, the skill registry serving the OpenClaw agent framework, identified 341 malicious entries, of which 335 traced back to a single coordinated operation. That is roughly one in eight entries in a public registry, almost all of it one actor, in a marketplace that had existed for a matter of months.

What makes this category different from ordinary dependency risk is that there is frequently nothing to scan. A skill is markdown. The instructions are the payload. A malicious skill does not need to ship a binary or call an unexpected syscall; it can simply tell the agent, in fluent and helpful-sounding prose, to read a credentials file as part of a legitimate-looking setup step, or to post build output to a URL framed as a telemetry endpoint. Conventional software composition analysis has nothing to grab hold of, which is precisely why the defensive tooling has had to be rebuilt: the emerging framing across the artifact-management vendors is that agent skills are the new packages of AI and need the same control, visibility and scanning that open-source packages get, with semantic scanning of markdown and instruction sets at ingest rather than signature matching.

The research has moved quickly too. One formal analysis framework for skill supply chains combines static analysis, capability-based sandboxing and a dependency graph with lockfile semantics, and reports 96.95% F1 with 100% precision on a purpose-built 540-skill benchmark. Treating skills as a dependency graph with a lockfile is exactly the right instinct, and it is the instinct most in-house teams have not had yet because skills still feel like documentation.

The finding that should genuinely worry an architect is compositional. Working from 1,520 marketplace skills, researchers took the 651 that pass individual inspection, formed the 211,575 possible pairs, and found 22.25% of those pairs flagged as structural candidates for compositional risk, with roughly one in five flagged pairs surviving a stratified human audit as a genuine risk. Two skills, each entirely safe on its own, combine into an installed set that is not: one skill has legitimate reason to read a sensitive file, another has legitimate reason to make an outbound call, and an agent holding both has a data exfiltration path nobody approved. Your review gate is almost certainly per-skill. The risk is per-installed-set, and that is a different control entirely.

The Retrieval Failure Nobody Warns You About

Set malicious skills aside entirely and assume a clean, internal, well-intentioned library. There is a second failure mode that shows up quietly somewhere around the fortieth skill, and it produces wrong behaviour rather than an error message.

The problem is same-capability ambiguity. The retriever correctly identifies which family of capability the task needs, and then hands the agent the wrong member of that family: a sibling skill that shares the same domain, action and object, but points at a stale resource, omits a precondition, or encodes a procedure that was superseded eight months ago. Everything about the selection looks right, including to a reviewer skimming the agent's trace.

A benchmark built specifically to measure this used a 7,982-candidate pool and 661 helpful-versus-risky skill pairs, and found that across seven standard retrievers a top-three result list surfaces a risky same-capability sibling for 47.3% of queries. Close to half. Not because the retrievers are bad, but because the skills genuinely are near-identical in every signal a retriever can see.

In a real organisation this is not a hypothetical. Two teams both write a skill called something like deploy-service. One of them is the legacy path that still works for three services and will corrupt state on the other forty. The payments team writes a refund procedure; six months later compliance requires a new step and someone writes a second refund procedure rather than editing the first, because editing the first requires finding out who owns it. Nothing in the system deletes anything, so both survive indefinitely and an agent picks between them on the strength of a description sentence.

The fixes are unglamorous organisational hygiene rather than technology. One canonical skill per capability, enforced. Descriptions written to disambiguate from the nearest sibling rather than to describe in isolation, which is a genuinely different writing task and one most engineers do badly on the first attempt. A named human owner on every entry. And a deprecation path that actually removes things, because a library where creation is cheap and deletion never happens becomes an archive, and an archive is what the agent is retrieving from. This is the same lifecycle discipline that agent registries need for the agents themselves, applied one layer down.

The Real Bottleneck Is Authorship, Not Tooling

The window for this being an optional exercise is closing on a schedule that is easy to check. Gartner predicts that 40% of enterprise applications will be integrated with task-specific AI agents by the end of 2026, up from less than 5% in 2025, and its analysts have framed the planning window for defining an agent strategy as three to six months. An eightfold increase inside a year means the agents will arrive in your stack whether or not the procedural knowledge they need has been written down.

Here is the uncomfortable shape of the problem. The tooling is free and the format is trivial. What a skill library actually costs is senior engineering time spent articulating things that experienced people know and have never had to say out loud. The person who can write the skill explaining why that service is never called directly is the same person on the critical path of three deliverables this quarter. Skill authorship competes directly for the scarcest resource in the organisation, and it competes badly, because its payoff is diffuse and arrives later.

The governance layer, meanwhile, has already been built by the platform vendors. Enterprise guidance now exists for vetting, evaluating, deploying and managing skills at scale, and managed skill registries with centralised policy control are now a product category rather than a proposal. None of that helps with the actual bottleneck. A registry with nothing in it is a registry.

The approach that works is to stop treating this as a documentation project, because documentation projects fail for well-understood reasons and this one would fail the same way. Harvest instead. Every time a reviewer writes the same explanatory comment a second time, that comment is a skill. Every incident postmortem with an action item reading update the runbook is a skill with a validator attached. Every question a new joiner asks in week two is a skill, and it is the highest-value kind because somebody has already proved it is not obvious. Ten skills harvested this way beat a hundred written speculatively, and the harvesting fits inside work that is already happening.

Prioritise validators above everything else in the schema. A skill that says follow this deployment order is advice, and an agent under pressure will treat it as advice. A skill that ships a deterministic script confirming the order was followed converts the same knowledge into something an agent can be held to without a human watching. That is the mechanism that moves a task across the delegation gap, and it is also the mechanism that makes the surrounding repository trustworthy enough for agents to work in at all, which we have argued separately is where most of the real return on AI tooling lives.

Why This Inverts the Oldest Objection to Outsourcing

The oldest objection to working with an external development partner is that the knowledge leaves when the partner does. It has always been a fair objection, because it has usually been true. The understanding of why a system is shaped the way it is accumulated in the heads of the people doing the work, and what got handed back at the end was a repository, a handover call, and a wiki page that was already out of date.

Skills change what the deliverable can be. If the working agreement is that every non-obvious procedure a partner's engineers learn becomes a versioned SKILL.md in your repository, reviewed by your people and merged through your pipeline, then the engagement produces an artifact that outlives it. That is not a softer form of knowledge transfer; it is a harder one, because it is executable, it is diffable, and it either passes its validator or it does not. An outsourcing engagement that leaves behind a working skill library has transferred more than one that leaves behind a well-attended handover meeting.

This is the shape of engagement StepTo is built around. We are a senior-led nearshore partner based in Serbia, working with European and US clients in overlapping hours, and the overlap matters more here than it does on most work. Codification is conversational: extracting the rule from the engineer who holds it takes a short back-and-forth, three or four rounds of what about this case, and a same-day review. That conversation is cheap across a two-hour gap and close to impossible across a twelve-hour one, which is the practical reason skill libraries built by far-offshore teams tend to be thin and generic. Nearshore development is not merely a cost position on this kind of work; it is what makes the work possible at reasonable quality.

For the build itself we default to a dedicated development team rather than fixed-scope delivery, for the same reason a registry is not a project: a skill library is a system you operate, and the team that wrote the skills is the cheapest team to keep them current. Where the need is narrower, staff augmentation puts senior engineers inside your existing team, which is often the right shape when the knowledge to be captured is yours and what is missing is capacity to write it down.

The capabilities divide fairly cleanly. Building the agent surfaces, the validators and the retrieval layer is AI engineering work. Standing up the ingest gate, the scanning and the compositional review that the supply chain findings above make necessary is security engineering, and it should be scoped separately because it has a different acceptance test. The harder upstream question of which procedures should be automated at all, rather than how to encode them, is AI strategy work and is worth separating from the build so it does not get decided by whoever is writing the markdown that week.

There is a jurisdictional convenience worth naming for EU-based clients, since skills encode compliance procedures and sometimes reference regulated data flows: an engineering team inside the EU removes an entire category of cross-border argument from the review. If you want to size this before speaking to anyone, our rates are on the pricing page, how we run engagements is on the process page, and the case for the location specifically is set out in our Serbia overview.