Outsourcing Skills – How My Agents Stay Lean as Project Knowledge Grows

In post 16 I left a door open at the end. The section was called "Optional: Extending Agents with Skills," it was barely four paragraphs long, and I deliberately stopped there – because when you create agents, the first thing that matters is the role, not the specialized knowledge.

I'm writing this post because that "optional" has since become a fixed part of my setup. Not because a new standard was published, but because my own agent files forced me into it.

The trigger was unspectacular: after a few months of project work, my solution architect agent from post 12 was no longer a cleanly cut agent but a landfill. On every run where something didn't fit, I added another rule – how a sequence diagram should be structured, which sections a solution concept needs, how I want content date formats handled, why it has to use the v3 API of the content layer and not the v2 syntax. Every single one of these rules was justified. Together they formed a role description that nobody could take in anymore – not me, and evidently not the agent either, because it was precisely the rules from the middle of the file that were ignored most reliably.

Two things up front, so the frame is clear:

First: skills solve a context problem, not a quality problem. They don't make an agent smarter and they don't make generated code more correct. All they do is ensure the right knowledge is in context at the right time – and the rest is not. That is less than the hype promises, and more than it sounds.

Second: this is a file format, not a paradigm shift. A skill is a Markdown file with a bit of YAML on top. Anyone expecting a new era will be disappointed. Anyone underestimating the idea behind it keeps hauling prompt monsters around.

How an Agent Turns Into a Prompt Monster

The pattern is always the same, and I consider it the normal case, not my personal failure: an agent starts out lean and well cut. Then it meets the reality of a concrete project. It does something wrong, you add a rule. It does something else wrong, you add the next one. After twenty iterations the role description is a sediment of corrections – and the problem with that is not the file size, but what happens to this text inside the model.

Because a system prompt is not a rulebook that gets worked through. It is context, competing with everything else for attention. The Chroma study „Context Rot: How Increasing Input Tokens Impacts LLM Performance" measured exactly this across 18 current models: as input length grows, reliability declines non-linearly, and long before the context window is exhausted. The large context window on the spec sheet says nothing about how well a model listens across its full length.

The practical effect has a name: instruction drift. Instructions placed far up in the context are followed less reliably as the conversation grows. That is exactly what I observed – rule three from my agent file held, rule seventeen was a suggestion.

Anthropic did the math on how much context is created by carried-along tool knowledge alone in „Code execution with MCP": a workflow that loaded all tool definitions and intermediate results into context needed roughly 150,000 tokens; the same task with on-demand loading got by with about 2,000. That is 98.7 percent less – for the same result. The number refers to MCP tools, not skills, but the underlying principle is identical: the most expensive part of your context is what you carry without needing it.

I already wrote in post 17 that MCPs noticeably increase token consumption. This here is the same bill from the other side – except that this time it isn't external data moving into the window, but my own project knowledge.

What a Skill Technically Is

The good news: the concept is pleasantly unspectacular. A skill is a folder containing a SKILL.md – YAML frontmatter for the metadata, Markdown for the instructions. Optionally, scripts, reference documents, or templates sit alongside it. No framework, no API, no mandatory registry.

Anthropic first introduced the format for Claude in October 2025 and described it in „Equipping agents for the real world with Agent Skills" – two months later, in December 2025, came the release as an open standard including the specification at agentskills.io. The reason I take it seriously at all is precisely this opening up: the same skill file works today in Claude Code, GitHub Copilot and VS Code, Cursor, OpenAI Codex, Gemini CLI, JetBrains Junie, and OpenCode, among others. For my setup from post 16 – Claude Code and GitHub Copilot in parallel – that is the actual win: I maintain the project knowledge once, not twice in two dialects.

This is what one of my skills looks like – exactly the sequence diagram rule that previously lived in the agent file:

---
name: usecase-sequence-diagram
description: Creates Mermaid sequence diagrams for use case documents under docs/usecases/. Use when a use case is documented, extended, or revised.
---

# Sequence Diagram for Use Case Documents

## Procedure
1. Break the main flow of the use case into numbered steps.
2. Draw exactly one arrow between two participants per step.
3. Alternative flows as an `alt`/`else` block, error cases as an `opt` block.
4. Insert the diagram below the main flow, never above it.

## Binding Conventions
- Participants always in this order: user, UI, composable, content layer.
- German labels, no Denglisch ("Lädt Beitrag", not "Loads Post").
- No implementation details on the arrows – business steps, not method names.

## Anti-Patterns
- No diagram without a previously defined main flow.
- No participants that don't appear in the use case text.

The decisive mechanism behind it is called progressive disclosure and runs in three stages:

When the agent starts, only the name and description of each skill land in the context – just enough for the model to know the tool exists. Only when a task matches the description does the full SKILL.md get loaded. Reference files and scripts come one stage later still, and only if the instructions actually need them.

At its core, this is the same principle I pursue constantly throughout this series anyway: the agent doesn't get everything at once, but what matters for the current step. With the implementation plan steps from post 13 I portion the work; here I portion the knowledge.

Agent, Skill, Rules File, MCP – Who Actually Does What?

I had to sit with this question longer than I'd like to admit. By now this series has built up a whole set of mechanisms that all somehow "teach the agent something" – and if you don't separate them cleanly, the same rule ends up in three places. Here is how I sort it out:

The dividing line that helps me most in practice runs between the last two rows: a skill delivers knowledge, an MCP delivers data. How a sequence diagram should be structured changes maybe twice a year and belongs in the repository under version control – that's a skill. Which fields an Appwrite collection currently has changes with the next deployment and must be queried at runtime – that's an MCP.

And the dividing line between agent and skill is the one between identity and procedure. The business analyst stays the business analyst, whether it is drawing a sequence diagram or formulating acceptance criteria. But the solution architect needs the diagram instructions too – and at that point at the latest, they no longer belong inside a role description, but next to it.

My Rules for Cutting

The hard part about skills is not the syntax, but the question of what should become one in the first place. Four rules have crystallized for me.

Only on the second time. I don't create a skill because a piece of knowledge would theoretically be reusable. I create it when I copy the same instruction into a second agent file for the second time. That is exactly the DRY threshold I apply in code as well – before that it isn't an abstraction, it's stockpiling.

The description is the real interface. I underestimated this. At stage 1 the model sees nothing but name and description – so the description is the only thing the "load or not" decision rests on. A vague description like "helps with diagrams" will never be hit reliably. That's why I always state explicitly when the skill is to be used, not just what it can do. A skill nobody finds is a skill that doesn't exist.

Procedure instead of prose. My first skills were explanatory texts – and those worked badly. What works are numbered steps, hard conventions, and a section with anti-patterns. The same insight as with the implementation plan from post 13: an agent executes a procedure more reliably than it interprets an explanation.

Skills belong in the repository. Mine live under version control next to the code, not in a global configuration on my machine. That way they are visible in the diff, they apply to everyone – including an agent in CI – and they die with the project instead of rotting away in my toolbox.

As a side note, libraries are starting to ship this themselves. FormKit now explicitly positions itself as the "form framework for coding agents" and sets up the matching skill for Claude Code, Codex, Cursor, Cline, Gemini, or OpenCode with a single command – npx formkit skill – including framework detection. For the libraries that offer this, it is the fastest path to an agent that doesn't hallucinate the API but knows it.

The Headwind: Skills Are Not the Answer to Everything

And now the part I found most interesting while researching – because it contradicts my own enthusiasm.

Justin Schroeder, the mind behind FormKit, argues in his talk „The Future Is Domain-Specific Agents" precisely not for equipping an agent with skills. He contrasts two architectures: the single agent whose context you keep inflating with tools, skills, and MCP servers – inheritance – versus many small, specialized sub-agents coordinated by a top-level orchestrator – composition. For the second variant he cites token efficiency gains of over 80 percent, the ability to use considerably smaller and cheaper models, and hard capability limits as a security advantage. His prediction: domain-specific agents will become the norm by the end of 2026, and 2027 will be the year of multi-agent orchestration – driven by rising token costs.

In that reading, skills are part of the problem rather than the solution.

I think the contradiction can be resolved, and here is how: anyone who has only one agent and wants to turn it into a universal genius with thirty skills merely shifts the problem one level down. Because the descriptions of all thirty skills sit in the context at every startup – and the selection decision gets blurrier with each additional entry. Progressive disclosure moves the limit upward; it doesn't abolish it.

So the actual pattern is: cut first, then outsource. That is exactly why it fits together for me – my setup from post 12 through post 14 already is the composition Schroeder means: five specialized roles with clear boundaries instead of one do-it-all. The skills sit inside that division and solve a different problem there – namely that specialized knowledge repeats across several of those roles. If my agents weren't cleanly cut, skills wouldn't cure that mistake, they would just make it more comfortable.

An Honest Point: What Skills Don't Solve

Skills do not turn a probabilistic model into a deterministic system. That sounds banal, but it is the limit I have seen overestimated most often.

A skill is an instruction, not a guarantee. Whether it gets loaded is decided by the model based on a text description. Whether the loaded instructions are then followed step by step is decided by the same model. There is no compiler that reports a skill violation. So exactly what I wrote in post 19 about the difference between guardrails and declarations of intent applies here: a rule only becomes reliable once it is checked deterministically – through types, linters, tests, a CI stage.

Concretely, for my blog project this means: the convention that content dates are only processed via parseContentDate() lives in a skill and is enforced by a validation script in the build. The skill ensures the agent usually gets it right straight away; the script ensures it never slips through wrong. You need both, and the order of importance is unambiguous – if I had to choose between skill and build gate, I'd take the gate.

And the second honest point: skills solve none of what this series is actually about. They replace no use case, no solution concept, and no Human-in-the-Loop checkpoint. A perfectly equipped agent implementing the wrong requirement merely builds very convention-compliant nonsense.

Conclusion

Skills solved a problem for me that I had long considered a law of nature: that agent files inevitably turn into landfills over a project's lifetime. They don't have to. The role stays small and stable, the specialized knowledge moves outside and is fetched when needed – and when I change a convention, I touch one file instead of five role descriptions.

What I don't kid myself about: this is a cleanup and maintainability improvement, not a quality revolution. My agents haven't become smarter, they have merely become less forgetful. And Justin Schroeder's talk is a healthy reminder that the answer to an overloaded agent is sometimes not "better skills" but simply "two agents."

In the end it's the same question as in code: where do I cut, and what belongs together? That this question now applies to prompts as well is something I find rather reassuring – it is a discipline we already know as developers, just applied to a new material.

How do you handle this? Does your project knowledge live in one large rules file, in the agents themselves, or already in outsourced skills – and have you hit the point where an agent file grew too large to still have an effect? I'd genuinely like to know.