Every codebase has rules that live nowhere. Errors are wrapped a particular way. Tests use one assertion style. There's a utility for date formatting and a reason nobody should import the library directly.
New developers absorb this through review. AI assistants don't absorb it at all: they suggest the generic answer forever, and you correct the same thing every week.
Skills fix that with a plain Markdown file.
The mechanism
Create .vexi/skills/ in your project and add a file:
# Error handling
Wrap all external calls in `Result<T, AppError>`.
Never throw across a module boundary.
Use `AppError.from()`, not the constructor directly.
# Testing
Vitest, not Jest. Co-locate tests as `*.test.ts`.
Assert with `expect(x).toBe()`; avoid snapshots.That's the whole format. No schema, no YAML, no registration step. Vexi loads it and follows it.
Because it's a file in the repo, it's version-controlled and shared. Your conventions arrive with a git clone, which is the same way the rest of your project's rules travel.
Write rules, not documentation
The common mistake is writing an essay. Skills work best as short, checkable, imperative statements: the things you'd write in a code review, not a wiki page.
- Good: "Use named exports. No default exports."
- Poor: "We generally think named exports are preferable in most situations for maintainability reasons."
The second sentence gives the model room to decide your rule doesn't apply this time. The first doesn't. Every skill file competes for context with your actual code, so brevity is a feature: a hundred crisp lines beat a thousand hedged ones.
Let Vexi write them for you
If articulating your conventions from a blank file feels like work, Vexi Learn takes the other route. It mines your past sessions for places where you corrected the AI, and drafts a style skill from the patterns it finds.
Your corrections are the highest-signal record of your preferences that exists, since you only bother correcting things you actually care about. Learn turns that history into a starting file you can edit down.
Sharing skills, and the trust question
Skills can be shared by GitHub URL, which is genuinely useful for a team standardising across repos. It also deserves care, so it's worth being explicit about the risk.
A skill file is instructions for an agent that can edit files and run commands. Loading one from a URL is closer to running someone's script than to reading their docs. A hostile skill could tell the agent to do things you would not want done.
Vexi therefore shows you the fetched content and requires explicit confirmation before trusting anything remote. Read it properly, not skimmed, the way you would a shell script from an unfamiliar repository. For skills from outside your own organisation, that reading is the entire security boundary.
Start with three lines
The best first skill file is nearly empty. Add the three conventions you're tired of restating. Add more the next time you find yourself correcting the same thing twice.
Skills earn their keep by accumulating slowly, which is also how the knowledge got into your team's heads in the first place.