Why You Should Ship an Agent Skill That Installs Itself With Your Library · Sander ten Brinke
Table Of Contents
Introduction
Link to heading<br>Like many developers, my approach to software development has changed a lot with the rise of AI. However, whenever I am using a library, I notice that the quality of AI Coding Agents drops. Deprecated or old ways of working are used, code is generated that doesn’t flow nicely with the code around it, etc.<br>But the main problem is that often, the model just doesn’t really know what to do with the library. For example, let’s say you installed a library to help you write better tests for a specific part of your system. In my case, I was using<br>Mockly by<br>Dennis Doomen to make testing HttpClient code easier. But even though I installed that library, the agent didn’t use it, opting instead for a more verbose technique.<br>This makes sense. The dataset of the model probably doesn’t contain the latest information about the library. Another reason is that AI tries to write code similarly to existing code, so the more you use agents to write code, the more “incorrect” code is generated and the (new version of the) library gets ignored.<br>In this post, I’ll discuss several approaches I have found helpful to deal with this problem. But most importantly, I want to talk about a powerful concept I’ve not seen a lot of people talking about, which is shipping Agent Skills together with your library. I saw<br>Daniel Cazzulino talking about this method<br>on Twitter for the<br>StructId library, and I discussed it with Mockly’s maintainer who then adopted it too. Since then, my agents have gotten noticeably better!<br>Here’s the part I find most exciting, and the reason for the title: in .NET, you can ship that skill inside the NuGet package itself. When a developer adds your library, the skill installs into their repository automatically. No plugin to discover, no extra command, nothing to remember. We’ll build up to that, but first let me cover what a library consumer can reach for today.<br>What's an Agent Skill?<br>If you’re unfamiliar with<br>Agent Skills, they are a way to teach AI coding agents how to perform a specific task. Basically, a skill is just a folder with a Markdown file (and optionally some scripts or extra files) that contains focused instructions the agent can load on demand.
This isn't just useful for .NET!<br>This post covers the .NET ecosystem, but the concepts apply to other languages and ecosystems too. If you get it working elsewhere, I’d love to read your write-up.
Teaching Agents About Your Dependencies
Link to heading<br>As a consumer, you have a few ways to give an agent better information about a library you’ve installed. Each one helps, and each has a catch:<br>ApproachWhat it doesWhy it’s not enoughContext7Indexes a library’s docs and serves them to the agentDocs can be stale or missing (it has nothing for Mockly), it eats a lot of context, and you’re trusting a 3rd party to inject instructions into your agentAGENTS.md rulesTell the agent to prefer installed libraries, or to web search their docsManual to maintain, and the web searches make the agent slower and burn tokensdotnet-inspectDecompiles the library so the agent can read its real API (also bundled with<br>Aspire’s Agent Integrations)Slow; most tasks don’t need a full decompileWrite a skill yourselfA focused skill the agent loads when it touches the libraryWorks well, but every consumer writes and maintains their own copyThat last row is the clue. If a skill is the right tool, why should every consumer write the same one? The library author already knows how their library should be used, so they can write the skill once and everyone shares a single definition. But how do you ship it?<br>One option is the plugin systems of agents like<br>GitHub Copilot and<br>Claude Code. But that doubles the work: the consumer installs the library and the plugin, and they can forget the plugin or never learn it exists.<br>There’s a better way.<br>Shipping Agent Skills Together With Your Library
Link to heading<br>If a library author already knows how their library should be used by an agent, why should that knowledge live in a separate plugin you have to find and install? It should come along with the package. When you add the library, your coding agent immediately has the right instructions. No web search, no decompilation, no separate plugin to remember.<br>Libraries already ship human-readable READMEs for developers. This is the same idea, aimed at AI coding agents instead.<br>So how does this work? You pack a SKILL.md file into your library, together with instructions on where the build/install system should store the skill. In .NET, we’d use the buildTransitive .targets file.<br>If you’re not a .NET developer: a NuGet package is the standard way to distribute .NET libraries, and a .targets file is an MSBuild file that can run extra...