The Skills System
How to encode hard-won knowledge into reusable skill files so that every future project benefits from everything you've already figured out.
CLAUDE.md tells Claude what your project is. Skill files tell Claude how you do specific things — with all the hard-won knowledge from the last time you did it baked in.
The "Why First" Scenario
You set up Supabase Row Level Security for the first time on Project 1. It took three hours. You read the docs, tried things that didn't work, figured out the correct policy syntax, understood why a certain approach caused a permissions error, and eventually got it right.
Project 2 starts. It also needs Supabase RLS.
Do you spend three hours on it again? Do you hope you remember what you figured out? Or do you have a document that says: "Here is how we set up RLS. Here are the exact patterns that work. Here are the mistakes I already made so you don't make them again. Here is the production-ready code."
A skill file is a cheat sheet for Claude — written in your patterns, with your decisions, after your real-world experience.
The difference between a trainee who builds Project 1 in 3 weeks and Project 2 in 1 week is the skills system. Every project makes the next one faster.
The Excel Analogy
Every experienced CA has a set of Excel templates they've built over years. They don't build a GST reconciliation model from scratch every month — they open the template they built after learning exactly which formulas work and which cause errors, adjust the inputs, and run it.
Skill files are your templates — but for code. They don't contain the finished product. They contain the patterns, the decisions, and the approaches that are pre-proven.
Where Skills Live
Skill files live in ~/.claude/skills/ — a folder in your home directory, not in any specific project. This is intentional. Skills are yours. They travel with you across every project on your machine.
How Skills Are Referenced
Skills aren't read automatically — you tell Claude when to read them, by adding references in CLAUDE.md.
In your global ~/.claude/CLAUDE.md, you'll have a section like this:
When you start a task, you can also explicitly tell Claude:
Claude will read the skill file, absorb all the patterns and rules inside it, and then apply that knowledge to your specific task.
What Makes a Good Skill File
A weak skill file is a list of docs links and generic advice. You could have just Googled that. A strong skill file has three qualities:
1. It's battle-tested. The patterns in it actually worked on a real project. Not hypothetical. Not copy-pasted from a tutorial. Proven in production.
2. It has an anti-patterns section. The most valuable part of any skill file is the "never do this" section. This is where real experience lives — the things you tried that failed, the approaches that seem right but aren't.
3. The code is production-ready. If the skill contains a code snippet, that snippet should be the actual pattern you use, not a simplified illustration. You should be able to use it directly.
Your First Skill File — Step by Step
After completing Project 1, write your first skill file. Here is the structure to follow:
Create the file
Write the header section
Document what you actually built
Don't write generic React advice. Write what you actually did — the exact approach that worked, the decisions you made, and why. Be specific to your experience, not a copy of the docs.
Anti-Patterns (Never Do These)
- Never use
useEffectto fetch data — use React Query'suseQueryinstead - Never put component logic in the return statement — extract to variables or hooks
- Never exceed 150 lines — if a component is getting long, split it
- Never use
anyin TypeScript — not even as a temporary measure
Update your CLAUDE.md to reference it
In ~/.claude/CLAUDE.md, add the skill to your reference table.
The Living System: Skills Must Grow
A skill file that hasn't been updated since you first wrote it is a liability. Patterns change. Better approaches emerge. Libraries update. If the skill is stale, Claude will apply outdated patterns.
The post-task scan (do this at the end of every significant task):
Ask yourself four questions:
- Did I solve something today that no skill file covered? → Add it.
- Did I find a better approach than what a skill currently documents? → Update it.
- Did something go wrong that the skill should have warned against? → Add it to anti-patterns.
- Did I figure something out from scratch that I'll need again? → Document it now.
This takes three minutes. Over six months, it compounds into a skills library worth thousands of hours.
The Skills Table (What You'll Build Over This Workshop)
By the end of the workshop, you should have at minimum:
| Skill File | You Write It After |
|---|---|
react-patterns.md | Project 1 — first React components |
supabase-patterns.md | Project 2 — first Supabase integration |
ui-design.md | First time you make real visual design decisions |
error-handling.md | First time you add proper error messages to a UI |
typescript-patterns.md | First time you wrestle with complex TypeScript types |
deployment-runbook.md | First production deploy |
Each one starts simple. One or two patterns. An anti-patterns section. A few code snippets. Then it grows.
The best time to write a skill file is immediately after finishing a task — while the memory of what worked and what didn't is fresh. "I'll write it later" reliably becomes never.
Why This Separates You From Generic AI Users
Anyone can open Claude.ai and ask it to write code. The people who build truly consistent, production-quality projects are the ones who have encoded their standards somewhere Claude can read.
When you have a well-maintained skills library:
- Every project follows your patterns — not whatever Claude defaults to
- Complex setup tasks that once took hours take 15 minutes
- New projects don't repeat the mistakes of old ones
- Your Claude Code is personalized to your workflow in a way no one else's is
This is the compounding asset that makes the AI-augmented developer more productive every month, not just today.