Skill Files Explained: How I Customized Claude Code for My Own Projects

Claude Code without customization produces competent but generic code. It knows Next.js. It knows Supabase. It does not know that this project uses $md$...$md$ dollar-quoting for SQL, that server components should fetch directly from Supabase without an API layer, or that the admin panel wraps every page in <AdminGuard><AdminShell>.

Skill files encode that project-specific knowledge. The result is code that fits the existing codebase instead of code that is correct in the abstract but diverges from how this project actually works.

What a Skill File Is

A skill file is a markdown document that lives in the project directory (typically .claude/skills/ or at the project root). When you invoke the skill, Claude Code reads it and applies its contents to the current session.

It is not code. It is instructions. The skill file tells Claude Code: who you are building for, what the stack looks like, what conventions to follow, and what to never do.

The Skill File Format

A minimal skill file:

---
name: portfolio-dev
description: Development conventions for santoshpaudel.me
---

# Stack
- Next.js 15 App Router
- Supabase (PostgreSQL, Auth, Storage)
- Vercel deployment
- Tailwind CSS
- TypeScript throughout

# Conventions
- Server components fetch directly from Supabase — no API layer for reads
- All admin pages wrap in <AdminGuard><AdminShell>
- Blog content uses $md$...$md$ dollar-quoting in SQL seed files
- Route params are Promises in Next.js 16 — always await params before destructuring
- Reading time uses readingTime() from lib/seo, not an inline calculation

# Never do
- Never use raw <img> tags — always Next.js Image component
- Never commit .env.local or API keys
- Never use blocking systeminformation calls in request handlers
- Never git add . — always specify files explicitly

The Skills I Actually Use

portfolio-dev — The conventions for santoshpaudel.me, as above. The most frequently invoked skill. Used in every session working on the main site.

sql-seed — Conventions for writing Supabase seed files. Dollar-quoting, ON CONFLICT DO NOTHING, column order, the specific table schemas. Without this skill, Claude Code occasionally writes seed files that are technically correct SQL but diverge from the established pattern.

deploy — The commit, push, deploy sequence. Which files to stage, what the commit message format is, what to verify before pushing. This skill is invoked at the end of a feature to handle the deployment sequence.

session-start — A meta-skill invoked at the start of each work session. It reads the current session note (NOTES.md), loads the relevant project skill, and summarizes where the work left off. This is the context restoration step.

Building a Skill File for a New Project

The fastest approach: let the first session of a new project be exploratory, then document what you learned.

Work on the project for 2–3 hours. Notice when Claude Code produces code that does not fit the conventions — wrong pattern, wrong location, wrong naming. Write those conventions down as you encounter them. After the first session, you have the core of your skill file.

Add to it over time. The skill file for santoshpaudel.me grew from 15 lines to 80 lines over six weeks as I encountered edge cases that needed encoding.

The Leverage Point

The leverage in skill files is not the obvious conventions (use TypeScript, use Tailwind). Those Claude Code follows anyway. The leverage is the project-specific constraints that are not in any documentation:

• —How the RLS policies work in this specific database
• —Why the admin shell wraps certain pages but not others
• —What the dollar-quoting convention is for SQL
• —Why certain packages are in serverExternalPackages

These are the decisions that took time to make and that Claude Code has no way to know without being told. Encoding them in a skill file means you make each decision once, not once per session.

---

Resources

• —Claude Code customization documentation — the official guide to skill files, CLAUDE.md, and project-specific configuration
• —Claude Code — getting started — how to install and configure Claude Code in a new project directory

Related Posts

• —My Claude Code and Antigravity Workflow for Running 3 Projects at Once — how skill files fit into the broader daily workflow
• —Running 3 Projects at Once: My Multitasking System With Claude Code — the session note pattern that pairs with skill files for context restoration
• —Commit, Push, Deploy — All From One Prompt — the deploy skill that closes out the session using the same system

---

Want a Claude Code setup tuned to your specific codebase? I configure the full workflow — skill files, session structure, deploy pipeline — as part of every project. Get in touch.