Skills-as-Code: Teaching an AI Agent Your Stack in a Week
Why an AI agent doesn't know your stack — and how to fix it for good. Skills are rules-as-files that the agent applies automatically.
Skills-as-Code: Teaching an AI Agent Your Stack in a Week
The number one complaint I hear about AI coding: "it doesn't know our stack." And that's true. Claude Code, Codex, Cursor — they all know Kotlin, Python, TypeScript in general. But none of them knows that you store money as Long kopeks, that errors live in sealed Exceptions via Either, and that a Verticle inherits from AbstractShivaVerticle with a specific lifecycle.
When a developer tries AI and gets back "foreign" code, they reasonably conclude the tool is useless. But the problem isn't the tool. The problem is that nobody gave the tool the rules.
Skills are rules-as-files. Each skill is a 50–200 line markdown document describing one pattern: when to apply it, what correct code looks like, and which anti-patterns exist. The agent pulls in the relevant skills automatically based on the task description.
On a recent project I reverse-engineered three reference repositories of a fintech company and, in a week, created 15 skills — from bootstrapping a microservice to serializing the wire protocol. After that, the agent generated code indistinguishable from the in-house team's. Not "similar" — indistinguishable. The client accepted 24 modules with no style remarks.
How It Works in Practice
You take an existing repository, find a recurring pattern (endpoint, consumer, test, migration), and describe it in a skill file: what to do, how to name things, what to inherit from, which imports to use, which anti-patterns are forbidden. You hand the agent a task, look at the result, and iterate the skill until generation is stable. Usually 2–3 iterations.
The key insight: a skill is written once and applied on every feature. It's a compounding asset — the more skills you have, the more predictable the generation and the less manual review you need. By the 15th skill, the agent starts producing merge-ready code on the first attempt.
Creating one skill takes 2–4 hours. A set of 10–15 skills for an average stack is about a week. After that, any developer on the team using the same AI tool generates code in a single, unified style. Skills don't walk out the door with people — they live in the repository.