Your skills should live with your documents

A factory requires repeatability

I recently went to the AI Engineer conference in Paris, and it was quite clear that “software factory” is the buzzword du jour, with a meaning that is fuzzy at best. Since this series focuses on that very topic, I’ll make my definition clear: an AI software factory is the set of tools and processes that allows us to build software in high volume while keeping control over the cost and output quality.

Getting control depends on achieving repeatability, a hallmark of manufacturing.

Software engineering teams currently face a significant problem in that respect. While adoption of AI tools has exceeded 90% in most tech teams, most CTOs I’ve talked to tell me the same story: they have two or three star AI users in their team who do great things, but what those power users do doesn’t diffuse to the rest of the team. In other words, AI software tools largely remain individual tools and AI software engineering is still more augmented craft than manufacturing.

The test is a simple question: how easily can your existing AI practice be transferred to a new engineer? For example, if a new engineer joins the team and you tell them “Please create a tech design for this feature”, how likely is it that they will run this process as well as your best engineer?

I’m focusing on the process, because in a factory you use tooling and process to drastically reduce variance in the output. Once your outcome is repeatable, you can improve it for everyone at once.

Documents of the intention layer

As I explained in my previous post, I believe that in order to build an AI software factory, we need to make intent the primary product of our factory with code only a byproduct; I call that intentional engineering.

In practice, intent lives in documents describing goals, problems to solve and how to get there, in natural language. You could see three types of documents: diagnosis documents (such as audit reports, monitoring outcomes, logs etc.), decision documents (tech designs, architecture decision records or ADRs, RFCs) and implementation documents (tasks or tickets). Some of those types can be combined into a single document. For example, a tech design might combine a problem analysis with a decision and the solution paths considered and rejected.

To ensure that we have a team tool, that intent should be easy to share. Finding information in a conversation is unwieldy even for the person who drove it, and untenable for anyone else, so we should treat agent conversations as ephemeral, with their conclusions written to durable documents. Those documents are the primary product of the factory, and they’re what you hand over to pass context along.

However, context alone isn’t enough. The diffusion issue I opened with shows that what is hard to transfer is the practice. How do we handle that?

Skills are units of workflow

Skills were introduced as a context management tool, allowing the agent to load dedicated instructions only when it believes they are needed. In that view, your agent is the one that chooses which skill to use at any given time.

That is not typically how I use them. During the course of my day as a software engineer, I know what task I want to carry out at any given moment, and I express it to the agent by using a particular skill. Every action I take is expressed as a skill.

So we now have two pieces for a factory workflow:

• Every step in the flow is captured in a skill.

• Every action reads from a document and writes back to it.

Combining them, we obtain a workflow where every action taken is a skill applied to a document.

Skills are unit of workflow, run on a document

This is where the concept of intentional engineering becomes concrete. Documents get transformed as they move on the conveyor belt of our factory; skills are the transformation units.

Your workflow can now be defined entirely in terms of skills. I find that to be one of the most interesting aspects of AI: it allows you to be fairly process-driven with shared skills describing that process, but you still have the full flexibility of an AI agent at every step. We can keep track of the history of skills that were applied to a document and the agent that received the trigger, giving us insights into how our workflow is actually run. In my first post I argued that decision lineage is vital to running a software factory; here we get a different kind of lineage through workflow observability.

Skills shouldn’t live with your agent

If my agent doesn’t choose skills anymore, it doesn’t even need to be aware of the list of available skills. With the approach described above, skills aren’t just capabilities available to one individual agent running in one particular location. Instead they become a common work grammar defined and owned by your team, and made available to every team member.

Skills don’t just act on documents, they produce the documents the next skill acts on. A triage skill turns a Sentry report into a diagnosis; a design skill turns that diagnosis into a tech design; sequencing turns the design into tasks. The output of one step is the input for the next, and running a workflow produces a chain of documents, with skills as the links.

It thus makes sense to co-locate your skills with your documents, as action triggers on those documents, presented alongside them. Note that my point is not about skills distribution here, that question is orthogonal – you could keep using the shared skills repository that many teams have set up as the underlying mechanism. My claim is about where skills are invoked from; I’m arguing they shouldn’t be invoked from the context of one individual agent, but from a team control plane that governs skill authoring and versioning, and also holds your team’s intent documents. The trigger gets routed to one agent from the control plane

Your skills should live close to your intent documents (example UX)

The way this trigger works can then be entirely agent agnostic. Each agent only needs a common CLI or MCP; the trigger becomes a command to run the skill, which returns the skill prompt concatenated with the document body.

Skills can live in your control plane, and get called remotely via MCP from each agent.

The skill is no longer something one agent has; it’s something your team owns, and the agent is just where it runs.

Conclusion

The approach described above turns your AI setup into team tooling: you take actions by using shared skills on shared documents. The agent receiving the trigger might be running locally on your laptop, but that becomes an implementation detail; the agent’s input and output live on shared tools.

Going back to the transfer test that I mentioned in my introduction: with a document-centric workflow and shared skills, launching a design process should just mean triggering the right skill on an embryonic document. That process can be handed to the new engineer in one sentence, it’s a concrete action on a concrete artifact.

Overall knowledge of the workflow still rests with your engineers – they decide what to do and when, as I believe they should. Now, however, they’re composing from a set of team-owned building blocks (documents and skills) rather than starting from scratch each time. The decision-making still rests with humans, but the variance in how each step is executed drops.

My sequencing skill is the best illustration of this: it turns a set of decisions (an ADR or tech design) into an ordered set of tasks, so the sequence itself is an artifact the team shares, rather than knowledge in one person’s head or a black-box todo list in one AI agent. That’ll be the subject of my next piece.