Structured skills and context docs for AI coding tools — cutting re-prompt cycles and helping teams ship faster.
An AI coding tool knows how software is written in general. It doesn't know how software is written here — which error shape this codebase returns, where caching belongs, which of the three state patterns in the repo is the current one and which two are leftovers nobody has migrated yet.
So every session starts from zero. Someone describes the convention, gets back something reasonable but wrong for this codebase, corrects it, gets it closer, corrects it again. The code that eventually lands is fine. The three rounds of correction that produced it are pure overhead, and they happen again tomorrow, in a fresh session, for the same convention.
What that overhead really costs shows up in review. Generated code that works but doesn't match the house style is the most expensive kind to review — it isn't broken, so there's nothing to point at, just a reviewer explaining the same preference for the fourth time this month. Some of those comments get made. The rest get waved through on a busy day, and the codebase drifts a little further in a direction nobody chose.
The knowledge itself was never missing. It was in reviewers' heads and in the existing code, where a tool starting fresh each time could not reach it.
We introduced structured “skills” — reusable context documents that encode a team's actual conventions (endpoint patterns, caching structure, frontend design, state management, database schemas) so an AI coding tool follows them automatically instead of being re-prompted into compliance each time.
A skill isn't a style guide. A style guide is prose someone reads once; a skill is written to be loaded at the moment it's relevant and to be specific enough to act on — the rule, a real example from this codebase, and the wrong version that keeps getting written by default. That last part does most of the work. Telling a model what good looks like is far weaker than also showing it the near-miss it would otherwise produce.
We rolled skills out across the whole application — backend, frontend, and shared services — so the AI tool picked up the team's conventions on its own instead of needing to be re-taught. Coverage across the stack matters more than depth in one corner: a tool that gets endpoints right and component structure wrong still produces changes that need correcting before they can merge.
Four things, written once, instead of the same correction every session.
Written against what the team already enforced, not against what a style guide said it should.
Writing the documents is the easy part. Deciding what belongs in them is not.
Most real conventions live in reviewers' heads and are only visible as the comment they leave. Getting them onto a page means watching what gets corrected rather than asking people to describe how they work — the answers to that question are always tidier than the practice.
Some conventions are load-bearing and some are one senior engineer's taste. Encoding the second kind gives a personal preference the authority of a standard, and the team finds out only when a tool starts enforcing it on everyone's code.
Every skill loaded is context spent, and a tool given fifty documents attends to none of them well. Skills have to be scoped so the relevant few come along with a change instead of everything arriving at once and diluting each other.
The team shipped faster while maintaining consistency across the application — with real, regular adoption, not a one-off demo.
The change people noticed first was in the middle of the work: fewer rounds between describing a change and having something mergeable. The correction that used to happen every session happens once, in a document, and then stops happening.
The second effect is slower and matters more. Consistency stopped depending on who reviewed a change and how much time they had. New code came out looking like existing code by default, which means the codebase drifts less between refactors — and the conventions themselves became explicit artefacts a new team member can read, rather than knowledge transmitted one review comment at a time.
Anywhere structured skills keep an AI coding tool aligned with a team's actual conventions, across the stack.
Most teams adopting AI coding tools treat prompting as the skill — better instructions, sharper phrasing, a longer preamble. That gets you a good session. It doesn't get you a good codebase, because nothing about it persists past the tab it happened in.
The durable version is context engineering: deciding what the tool should know about this codebase, writing it where it can be loaded, and maintaining it like any other part of the repo. It's unglamorous work with a compounding return — every convention encoded once is a correction that stops recurring for everyone, on every change, from then on.
Real production experience inside an existing team's codebase — with measurable adoption and output, not a personal project.