Stop re-explaining your stack to Claude Code: a project-scoped skill folder system

Stop re-explaining your stack to Claude Code

If you use Claude Code daily, you know the ritual.

You open a session, and for the next 10 minutes you type variations of:

"This is a Next.js 14 project using App Router, TypeScript strict mode, Tailwind for styling, Supabase for auth and database, we deploy to Vercel, the file structure follows..."

Across 3-4 sessions a day, that's 30-40 minutes of pure context-setting. Multiply by working days in a month and you get roughly 12 hours per month re-explaining the same thing to the same tool.

This article shows a small, boring, permanent fix. No prompts to copy-paste. No tool you have to remember to invoke. No subscription. It uses three Claude Code primitives you might already know about but likely haven't fully wired up: CLAUDE.md, agents with YAML frontmatter, and SKILL.md folders.

We'll build a minimal working example, then I'll show what a fully loaded setup looks like.

The three primitives

Claude Code automatically reads configuration from your project root on every session start. The three important pieces:

File	Location	What it does
CLAUDE.md	Project root	Free-form markdown. Claude reads it every session. Put your stack, conventions, commands, and "rules I'm tired of repeating" here.
Agents	.claude/agents/*.md	YAML-fronted markdown files. Each one defines a sub-agent with its own system prompt, model, and tool restrictions. Invoked with @agent-name.
Skills	.claude/skills/<name>/SKILL.md	Slash-command workflows. A SKILL.md file becomes /name. Great for repetitive multi-step work.

The win is that all three load automatically. You don't remember to use them — they're just there.

Step 1 — A real CLAUDE.md for freelance work

Here's a stripped version of what lives in my client projects:

# CLAUDE.md — Next.js client project

## Stack
- Next.js 14 (App Router) · TypeScript strict · Tailwind · Supabase (SSR)
- Deploy: Vercel · Package manager: pnpm

## Conventions
- Server Components by default. `"use client"` only where actually required.
- Zod for all user input validation. `react-hook-form` for forms.
- Absolute imports with `@/` prefix.
- Every `app/*` route must have `loading.tsx` and `error.tsx`.
- Never commit `.env*` files. Never log Supabase service role keys.

## Commands you can run
- `pnpm dev` — dev server
- `pnpm build` — production build (must pass before I commit)
- `pnpm type-check` — tsc --noEmit
- `pnpm lint` — ESLint

## Behavior
- Before any code change, run `type-check` and `lint`. If they fail, fix first.
- After any code change affecting routes, show me the diff before applying.
- Never assume a package is installed. Read `package.json` first.

That's it. Save it at the project root. Close your session. Reopen it. Claude now knows your stack without you typing a word.

The subtle but important part is the Behavior section. Most devs stop after listing the stack. The real value is encoding your own review rituals — the stuff you keep catching yourself reminding the model about.

Step 2 — A sub-agent for pre-delivery code review

Create .claude/agents/senior-dev.md:

---
name: senior-dev
description: Code review before client delivery
tools: Read, Glob, Grep
model: sonnet
---

You are a senior full-stack reviewer. Your job is to review code
BEFORE it ships to a paying client.

Check for, in priority order:
1. TypeScript errors or `any` that should be typed
2. Missing error handling on async boundaries
3. Supabase RLS issues — queries that bypass row-level security
4. Client/Server component split correctness (no client-only code
   in Server Components, no secrets in Client Components)
5. Accessibility regressions (missing aria-labels, bad contrast,
   non-semantic HTML)
6. XSS / unsanitized input in forms or URL params

Output format: a table with file:line, severity (high/med/low),
issue, and a one-line fix suggestion. No prose. No praise.

The tools: Read, Glob, Grep line matters — it means this agent is read-only. You can invoke it on a repo without worrying it'll edit files. Defense in depth for an LLM.

Now in any session you can type:

@senior-dev review src/app/dashboard

And you get a terse, structured report. No more "Claude I know you want to be encouraging but please just tell me what's broken."

Step 3 — A slash command for scaffolding

Create .claude/skills/dev-kickstart/SKILL.md:

---
description: Scaffold a new feature with consistent project structure
argument-hint: <feature-name>
allowed-tools: Read, Write, Glob
---

# /dev-kickstart

Given a feature name, create the full scaffolding:

1. `app/<feature>/page.tsx` — route using Server Component pattern from CLAUDE.md
2. `app/<feature>/loading.tsx` and `error.tsx` (per project convention)
3. `components/<feature>/<Feature>Client.tsx` — client component only if needed
4. `lib/<feature>/types.ts` — Zod schemas + inferred TS types
5. `lib/<feature>/queries.ts` — Supabase query helpers

Follow the naming conventions and import aliases from CLAUDE.md.
Do not install new dependencies. Do not commit. Show me the tree
of created files at the end.

Now /dev-kickstart auth-flow scaffolds a complete feature following your conventions, not generic ones.

The key difference versus a prompt template: this is a Claude Code native format. The YAML frontmatter tells Claude Code which tools to permit and how to label the command in the UI. It's a first-class citizen, not a string hack.

Why this beats prompt libraries

Prompt libraries (the "100 prompts for developers" PDFs you see everywhere) have three problems:

1. You have to remember to use them. A prompt sitting in a Notion page is functionally dead.
2. They're not scoped. A general prompt for "code review" can't know your Supabase tables or your import aliases.
3. They can't restrict tools. A prompt can ask nicely. A skill with allowed-tools: Read, Glob, Grep literally cannot write files.

Skill folders fix all three. They live in the repo, they load automatically, and they can scope capabilities.

What a fully loaded setup looks like

After using this pattern across a few projects, my client-work template grew into this shape:

your-project/
├── CLAUDE.md                          ← stack, conventions, rituals
└── .claude/
    ├── settings.json                  ← security defaults (block .env reads, etc.)
    ├── agents/
    │   ├── senior-dev.md              ← pre-delivery review
    │   ├── qa-tester.md               ← bug + a11y hunting
    │   └── client-communicator.md     ← drafts client emails
    └── skills/
        ├── dev-kickstart/SKILL.md     ← scaffold features
        ├── code-review/SKILL.md       ← full repo review
        ├── deploy-vercel/SKILL.md     ← pre-deploy checklist
        ├── generate-api-route/SKILL.md
        ├── create-component/SKILL.md
        ├── fix-bugs/SKILL.md
        └── write-tests/SKILL.md

Nothing fancy. Just boring discipline, encoded once.

The 15-minute starter

If you want the fastest version of this:

1. Create CLAUDE.md at your project root with sections: Stack, Conventions, Commands, Behavior. Write each section as bullet points of things you're tired of explaining.
2. Create .claude/agents/senior-dev.md with the template above, adapted to your stack.
3. Close your Claude Code session. Reopen it in the same project. Type @senior-dev review src/ on a random file.
4. Watch it work.

That's it. From here you add agents and skills as you catch yourself repeating instructions.

If you want the full bundle

I packaged my complete setup — 3 project templates (freelance Next.js, SaaS MVP, e-commerce Stripe), 3 agents, 7 skills, and a hardened settings.json — as a drop-in bundle. It's on Gumroad for $19 if you'd rather not assemble your own.

But honestly, the real value is in the pattern, not the bundle. Everything above is enough to get started. Copy the templates, adapt them to your stack, and watch your session start-up time drop to zero.

---

If you build your own skill folder, drop a comment with what's in it — I'm curious how other people structure theirs.