Skills
How a small markdown file can teach an AI assistant the conventions of your project before it writes a single line of code.
Every team has a set of unwritten rules. We use semantic tokens, never raw colors. We reach for a component before a styled div. We put gap on the flex parent, not space-y on the children. New engineers learn these rules over weeks by reading pull requests and getting reviews. An AI assistant gets none of that context — it shows up, reads your package.json, and starts guessing.
A skill is a small markdown file that fixes this. It loads on every interaction and gives the assistant the conventions a human teammate would have absorbed by sitting next to you.
What a skill actually does
It does not give the assistant new capabilities. It gives it preferences. Without a skill, asking for a "card with an image and a title" produces a reasonable guess: a div with rounded-xl, a shadow, maybe a hardcoded bg-white. With a skill, the same prompt produces a Card from your registry, semantic colors from your theme, and the radius your design system already uses.
The difference is not intelligence. It is context.
A minimal skill
A useful skill is shorter than people expect. Three sections is enough:
# This project
- Framework: Next.js App Router
- Styling: Tailwind v4 with OKLCH tokens in `globals.css`
- Components: shadcn/ui, installed in `src/components/ui`
# Conventions
- Always use semantic tokens (`bg-background`, `text-muted-foreground`).
- Prefer `gap-*` over `space-y-*`.
- Add `active:scale-[0.96]` to interactive elements.
# When in doubt
Run `shadcn info --json` to read the project before generating code.
That is most of it. The assistant now knows what "correct" means in this codebase.
The part that matters
The value of a skill is not the file. It is the act of writing it. Distilling your conventions into a page forces you to decide which rules are real and which are habits you have never questioned. Half the rules teams enforce turn out to be cargo from a project that no longer exists.
Write the skill, and you will find out which of your own rules survive being written down.
Related posts
Comments(5)
The concentric radius tip alone was worth the read. I’ve been matching outer and inner radii for years without realizing why it felt off.
outer = inner + padding— that’s the whole rule.Same — once you see it, you can’t unsee the mismatch on nested cards.
Exactly. Glad this landed.
Also useful with Typeset measure caps — nesting and measure fight each other if you’re not careful.
Clear writing on a topic that usually gets hand-waved. Would love a follow-up on how this plays with nested dialogs.