From Documentation to Executable Knowledge
Turning Team Practices into Executable Knowledge with Agent Skills
In my previous video, I explored a question that has been bothering me for a while, If AI can now generate in minutes what used to take us days, what are developers actually responsible for?
The answer I arrived at is not “writing better prompts.” It’s something more fundamental. It’s about breaking problems down, controlling the process, and iterating with intention. AI changes the speed of implementation, but it doesn’t remove the need for structure.
But after publishing that video, I realized something was missing. Even if we accept that our role is shifting toward decomposition and iteration, there is still a practical question that remains unresolved: how do we share that knowledge with others?
Because decomposition is not just an individual skill. It’s something teams need to align on, and historically, we haven’t been very good at doing that.
The Problem with How We Share Knowledge
In most teams, knowledge lives in one of two places. Either it lives in someone’s head, or it lives in a document. Neither works particularly well.
When knowledge lives in someone’s head, the only way to spread it is through pairing or constant communication. That can work in small teams, and in places like Thoughtworks, pairing does help a lot. But it doesn’t scale easily. It’s expensive, fragile, and heavily dependent on individuals. As the team grows, consistency becomes harder to maintain.
On the other hand, we rely on documentation. But documents have their own problems. They become outdated very quickly, they rarely capture all the edge cases, and they almost never keep up with how the system evolves. Over time, they turn into something people read with a bit of skepticism. You might follow part of it, but you don’t fully trust it anymore.
So we end up in an awkward situation. Free-form text is easy to write, but not reliable to follow. Code is precise, but not a good medium for sharing intent. And for a long time, we’ve just accepted this trade-off because there wasn’t a better option.
What AI Changes (and What It Doesn’t)
AI changes how fast we can implement things, but it doesn’t change how we should structure them. If anything, it makes structure more important. Because now it’s very easy to build something quickly without really understanding it, and once complexity accumulates, it becomes much harder to control.
The core loop is still the same. We break problems into smaller pieces, verify each piece, and iterate deliberately. The difference is that each step can now be generated much faster, which creates a new kind of pressure. We can move faster than our ability to align on how things should be done.
A Different Way to Capture Knowledge
Recently, I’ve been experimenting with something called Agent Skills, and I think this might be the missing piece.
A skill is not just a document. It’s a structured description of how something should be done, including when to use it, how to execute it, and what a good outcome looks like. It sits somewhere between documentation and code. Unlike a document, it’s meant to be used, not just read. Unlike code, it’s designed to communicate intent, not just implementation.
