One afternoon in production
VisionHeight builds a preemptive cybersecurity platform: autonomous agents investigate threats and deliver the findings to clients. A few weeks ago the publishing step of one of those agents failed. A client had asked it to put the full report in their workspace. Four files were supposed to appear. They never arrived, and the only clue in the logs was one line: mount path overlaps.
I know how that afternoon usually goes. If the engineer who wrote the publishing code is around, it takes one to two hours: read the code, dig through the logs, rebuild four files by hand in the house style, and drop whatever else was in progress. If that engineer is out, somebody else has to find the right repo, the right log group and the right cloud profile, work out that one early error is poisoning every later one, and learn what our deliverables even look like before rebuilding them. That is half a day. Realistically, tomorrow.
This time I opened a coding agent with our skill wiki installed and described the symptom. It read our "how we publish" skill, so it knew which files and which outbox. It read our infrastructure skill, so it knew which profile and log group to search. It found the cause, unstuck the session, regenerated the four files with our file-generation skill, published them, and wrote a ticket for the engineer who owns that code, with the fix. Thirty minutes end to end, and for most of them I was doing something else.
The bug itself was easy. Once you knew which logs to open and which code to read, it was obvious. What eats the afternoon is knowing where to look, and that is what the wiki gave me: it saved every minute of remembering how our own system works. Half a day became half an hour, and it would have been half an hour for anyone on the team, not only for the person who wrote the code.
Debugging is the dramatic example, but it is not the main one. The same wiki answers every question anyone in the company asks about how our own system works: which job writes this table, what this field means, why that score looks the way it does, how to pull last week's numbers. The analyst asking in a chat window and the agent answering a customer read the same skills. This article is about how we built that, what it got us, and how you could start on Monday.
The problem: your company's knowledge lives in heads, and AI guesses
Every company has this. Knowledge lives in people's heads, in notebooks, in scripts, in a document nobody updates. For people that is slow. With AI in the loop it is worse than slow, because the model does not say "I don't know". It guesses, confidently. Or it searches and relearns the whole organization from scratch, every session, which costs a lot of time and money.
A real question from our Slack: "Why did this score change between yesterday's run and today's?" The answer needed three rules in three different places that interacted on that one day. It lived in one notebook and in two people's heads. Nobody else could have answered it.
Our platform from the inside is hundreds of code folders, hundreds of tables, dozens of jobs running every night. A new engineer or analyst needed months to become productive, and most of that time went on walking over to a colleague and asking how something works.
There is a quieter cost too. An engineer edits one piece without knowing which code, jobs or schedules depend on it, and breaks something else. Nobody holds the whole system in their head, so this is not carelessness; it is the normal state of things.
What can be done, and why each option falls short
There are four ways to get your company into an AI's head.
- Write it all into the system prompt. It works for a page or two. Beyond that you pay for every word on every turn, and the prompt is a string frozen at deploy time. Nobody updates it, because updating it means a release.
- Keep a wiki for people (Confluence, Notion, a docs folder) and hope the AI finds it. People stop updating it within a month, and the AI on the desktop rarely reads it. When it does, it quotes the stale page with full confidence.
- Retrieval, RAG: embed everything and fetch the top chunks for each question. This is the obvious answer and it does work. Two flaws showed up fast. Results come in fixed-length chunks, and similarity stands in for relevance. The bigger problem is operational: a retrieval pipeline is a running service with an index you have to keep fresh, and you can reach it from a desktop assistant only by wrapping it in yet another service. Skills need no service and no index, and relevance is decided by the model reading a description, not by vector similarity.
- Skills, and this is the one that stuck. If you have not met the term: a skill is a folder you hand to an AI. On top sits one short file that says what the folder is about and when to open it. Below it is anything you want the AI to have: notes, reference documents, tables, scripts, examples. The AI reads the short file up front and opens the rest only when a question calls for it.
Skills give you three things. The AI decides on its own when the folder is relevant, so there is no retrieval query to tune. You pay for a skill only when it is actually opened; the always-on cost is one description per skill. And the same folder works everywhere: in the coding agents your engineers run, in the desktop and chat assistants your analysts already have open, in the hosted platforms where production agents run, and in any agent you build on an API. Same folder in all four, no changes.
Skills are a convention the model understands rather than a feature of one vendor's API, which is what makes them portable. The folder layout follows the open Agent Skills specification, which several agent tools now read. The rest of this article is about what we built on top of them.
The skill wiki
First the word. A wiki is a set of notes anyone can edit, linked to each other. Ours is a wiki in both senses: anyone can fix a skill, and every skill points to the skills it depends on ("to understand this, read that"), so the whole thing is a graph you can walk.
In practice it is one git repository with two halves, the part people write and the part machines make.
People write the skills, about fifty of them, one subject each. General skills say what a thing is, why it exists and how to think about it. Specific skills sit under a general one and explain how one part actually works, step by step. Optionally, there is a hub: one short map of the whole system that points to every general skill. We use one for the internal wiki, where an engineer's question could land anywhere, so the AI pays for one description up front instead of fifty. Customer-facing agents skip it; each of them has a few clear jobs, and separate descriptions are what make the right skill load.
People also write one config file that holds everything about every agent (which audiences it may read, where it runs, which skills it starts from) and the system prompts, which live next to the skills because they behave like skills: they need to stay fresh and go through the same review.
Machines make the rest. Scripts pull the generated facts from the live system: lists of tables and their columns, which jobs run when, an index of the code. Nobody types those. Then the build walks the graph for each agent, collects only the skills that agent is allowed to read, packs them, and publishes them.
The design rests on five ideas:
- Two layers of skills. The big picture, then the details. Context is a budget: a general skill is paid for whenever its subject comes up, a specific one only when a question drills into the mechanism.
- One pool, many agents. Write once, everyone reads.
- Audience tags are the only gate. Every skill is tagged internal, client-safe, or both. An agent reads a skill only if they share a tag. A skill with no tag reaches no one, so the default is safe.
- Facts that update themselves. Scripts keep the generated lists current.
- Automatic checks. A broken change does not ship.
The principle underneath all five: write what you know once, and every AI your people use, and every agent you ship, reads the same skills.
The two wins
Win 1: an internal wiki, in week one
The first win needs no agent at all. Distribute the skills once and every coworker's AI session starts with the company in its head, like a colleague who knows your stack. And it is not only engineers debugging. An analyst asks what feeds this dashboard and gets the answer in the chat window that is already open. A product manager asks what a field means. Someone in sales asks how a score is computed before a customer call. A new hire asks everything, and nobody has to walk over. An analyst who joined us recently wrote new tagging rules from raw data in her first week, work that used to wait until someone had months of context. Onboarding did not get faster because we wrote better docs; it got faster because the new hire's assistant already knew the system.
Win 2: client-facing agents on the same skills
The same skills, minus the internal ones, become what a customer-facing agent knows. An agent needs to know its tools (which one, when, and what comes back), its domain (the concepts of the field it works in) and its job (how to investigate and what a good answer looks like). With a raw prompt, all of that is a string frozen at deploy time. With the skill wiki it is a living set of skills that refreshes with the platform.
We have multiple production agents running on this today: two chat analysts, a Microsoft Teams bot, a nightly insights job and a brand-impersonation hunt, with more on the way. A new agent is a short list: prompt, tools, skills, schedule.
Why one place
Why not a prompt per agent and a wiki for people? Because they drift apart within a month. One pool, written once, refreshed once and reviewed once, serves the engineer in a coding tool, the analyst in a desktop assistant, the customer agent and the new hire on day one. A wrong answer anywhere points at one skill, and fixing that skill fixes every tool at once.
The hidden-dependency bugs from earlier mostly stopped too. The AI helping an engineer now sees the whole system, so the dependencies show up before the change ships.
Keeping internal knowledge internal
A customer talks to our agent directly, so anything in its context is quotable. That is why the tags encode exposure and nothing else: two audiences, no hierarchy. The one dangerous act is tagging a skill client-safe. No script can judge whether that is right, so a person reads every client-safe skill before it lands. Behind that there is a words check: a list of internal terms, and the build refuses to ship any customer skill that contains one. A client-safe skill is also written fresh at the customer's level, not trimmed down from the internal one.
What the repository looks like
You only ever edit the first three entries. Everything else is built.
This is the whole of agents.yaml for an invented example, a hotel concierge that guests can message. Guests may read the skills about amenities, check-out and the neighborhood; the VIP list and the room-rate rules are tagged internal and never reach them. This is how little it takes to define an agent: what it may read, what it starts from, what it can do, how it talks, where it runs.
That is the entire cost of a new agent: a block like this and a prompt file. Nobody provisions anything, nobody copies skills around. The build does the rest on the next merge, and the agent shows up with its knowledge already attached.
How it stays alive
A wiki that goes stale is worse than no wiki, because the model will quote it. Two mechanisms keep ours fresh.
The first is the refresh. The generators read structure only: table and column names, schedules, code paths, commit hashes. Never data, never notebook contents. So daily data churn produces no diff, and a changed commit hash is the signal that the prose about that code may be stale. Three times a week a scheduled agent regenerates the facts, notices what drifted, rewrites the affected skill and opens a pull request. A person reviews the data diff and the prose diff together, and approving is the release: the skills sync to every desktop and the production agents are reconciled on the same merge. There are no direct pushes. A change that bypasses the review has not shipped. And it is not a quiet job: in about one refresh in four, the facts moved enough that the prose had to change too, and a person approved the rewrite. That is roughly one narrative update a week, driven by real change in the system, not by anyone remembering to edit a page.
The second is the checks. Every time someone opens a change, one script asks four questions and lists everything that is wrong, not only the first problem.
- Does any customer skill contain internal words?
- Is every skill still in the right shape, with its links pointing somewhere real?
- Is every description short enough?
- Does every agent's prompt mention only skills that exist?
Any wrong answer blocks the change until someone fixes it. The checks catch mistakes; the human read of every customer-facing skill is still what catches meaning.
What changed at VisionHeight
Before the wiki, a question like "which job writes this table?" went to a Slack channel and waited there for hours, until one of the two or three people who knew noticed it. Everybody asked engineers, because engineers were the only place the answers lived, and answering was eating a serious part of their week.
Now the engineers say the same thing to everyone: "ask the chat." They mean it literally. The assistant on your desktop has the wiki installed, so it already knows the tables, the jobs and the schedules, and it answers in the window that is already open. The interruptions dropped, and the engineers were the first to notice.
My own day changed in three ways. I no longer answer the same questions over and over. I no longer start an AI session by re-explaining how our system works; the wiki does that before I type a word. And I no longer hunt for where things are, which log group, which profile, which repo. That was the thirty minutes in the story at the top.
And the pace of ordinary work moved. Coding agents make everyone faster, wiki or no wiki; what the wiki changes is what the speed is worth. Code reviews are done by the AI first, against the same skills, so a human reviewer reads a change that has already been checked for the things we always check.
Small features and bug fixes come back with fewer of the bugs that used to slip in, because the agent sees which jobs and tables depend on the code it is touching. Reports come back answering the question that was asked, because the agent knows what each field means rather than guessing from its name. And two things that depend entirely on knowing the system got dramatically shorter: bringing a new tool into our platform, which used to be a project, has taken about a day in our recent cases, and our last migrations of data and code between systems took days rather than the weeks we used to plan for. None of that comes from a faster model. It comes from the model not having to ask.
Start Monday
If you want to try this, here is the order that worked for us.
- Pick the subject everyone asks about. That is your first skill.
- Don't type the facts. Ask a coding agent to write the script that pulls schemas, jobs and repos from the live system.
- Write the first skills with the model as a consultant. You bring the why; it drafts and asks the questions a new hire would ask; you correct.
- Tag audiences and add the gate.
- Automate the refresh, as described above: a scheduled agent drafts the update, a person merges.
- Attach it to one agent.
Our own wiki came out of exactly this. A coding agent wrote the design doc, the scripts and the first skills with us, and the refresh job still drafts with a model today.
To make the first step shorter, we condensed all of the above into a single prompt file. Open an empty repo in whatever coding agent your team uses, paste it in, and it interviews you: about a dozen questions, each with a sensible default. By the end of the first session you have one agent and five skills, answering the five questions your team asks most. It is vendor-neutral and it is yours.
I think every company with more than a few dozen engineers should do this, and most won't, because from the outside it looks like documentation. It isn't. Documentation is written for people who may read it. This is written for a model that will read it, every session, in every tool your people open. Write it once, for the model, and everyone else gets it for free.
The jumpstart prompt is here: https://github.com/danaiz/skill-wiki-jumpstart.git
Dan Aizenberg is a Senior Data Scientist at VisionHeight, where he works on the data platform and the AI agents that run on it. He built the skill wiki described here and maintains it with the team.