Claude Code Skills Files Explained

Claude Code has a feature most people don't know about: skills files. They're simple markdown files that live in your project and turn Claude Code from a generic coding assistant into a specialized expert that knows your project, your preferences, and your process. This article explains everything about how they work and how to use them.

The Problem Skills Files Solve

Every time you start a new conversation with Claude Code, it starts from zero. It doesn't know your tech stack preferences, your coding style, your app's architecture, or the mistakes it made last time. You end up repeating yourself constantly:

• "Use TypeScript, not JavaScript"
• "We're using Supabase, not Firebase"
• "Follow the existing component pattern"
• "Don't put API keys in the client code"

Skills files solve this by giving Claude Code persistent context. Write it once, and Claude Code follows it every time — across every conversation, every session, every command.

The Two Types of Instruction Files

Claude Code uses two types of markdown files, and understanding the difference is critical:

1. CLAUDE.md — Project Instructions

This is a file called CLAUDE.md in your project root. Claude Code reads it automatically at the start of every conversation. Think of it as your project's "constitution" — the rules and context that apply to everything.

What goes in CLAUDE.md:

• What your app does (one paragraph)
• Tech stack and architecture decisions
• Coding conventions and style rules
• File structure and naming patterns
• Common pitfalls to avoid
• Environment setup and dependencies

Example CLAUDE.md

# FitSnap

## About
Calorie tracking app. Take a photo of food, get instant calorie and macro estimates.
Built with React Native (Expo), Supabase, RevenueCat, GPT-4 Vision.

## Architecture
- /src/screens/ — one file per screen
- /src/components/ — reusable UI components
- /src/hooks/ — custom hooks for data fetching
- /src/lib/ — utility functions and API clients
- /src/constants/ — colors, spacing, typography tokens

## Rules
- TypeScript only, strict mode
- Functional components with hooks (no classes)
- Use the design tokens from /src/constants/ — never hardcode colors
- Every screen must handle loading, error, and empty states
- All Supabase queries go through hooks in /src/hooks/
- Never store secrets in client code — use environment variables
- Test on real device before marking anything as done

## Current Status
- Auth: done (email + Google)
- Home screen: done
- Camera/scan: in progress
- Paywall: not started

With this file in place, Claude Code automatically follows your rules. You never have to say "use TypeScript" or "follow the existing pattern" again.

2. SKILL.md — Slash Command Skills

Skills are more powerful. They live in .claude/skills/[skill-name]/SKILL.md and they register as slash commands. When you type /skill-name in Claude Code, it loads that skill file and follows its instructions.

The difference between CLAUDE.md and skills:

How to Write Your Own Skills

A skill file is just a markdown file with structured instructions. Here's the anatomy of a good skill:

# /my-skill-name

## What This Skill Does
[One paragraph explaining the purpose]

## Step 1: [First thing to do]
[Detailed instructions for step 1]

## Step 2: [Second thing to do]
[Detailed instructions for step 2]

## Step 3: [Third thing to do]
[Detailed instructions for step 3]

## Rules
- [Specific constraints]
- [Quality checks]
- [Edge cases to handle]

Save this as .claude/skills/my-skill-name/SKILL.md and it immediately becomes available as /my-skill-name in Claude Code.

What makes a skill effective

After building 20 skills that I use every day, here's what I've learned about what makes them work:

• Ask questions first — the best skills don't just execute. They interview you. "What's your niche?" "Dark mode or light?" "How do you want to monetize?" The answers make the output unique instead of generic.
• Be extremely specific — vague instructions produce vague output. "Build a nice UI" produces garbage. "Build a dashboard with a circular progress ring showing remaining calories, using the green accent color from constants, with a pull-to-refresh gesture" produces something real.
• Include quality checks — tell the skill to validate its own output. "After generating the code, check for exposed API keys, missing error handling, and TypeScript errors."
• Chain to the next skill — at the end of each skill, suggest what to run next. This creates a pipeline: /find-idea → /validate-idea → /plan-app → /setup-project.

Real Example: A Security Audit Skill

Here's a simplified version of a real skill that scans your project for security vulnerabilities:

# /security-audit

You are a security auditor. Scan this project for vulnerabilities.

## Step 1: Check for Exposed Secrets
Search the entire codebase for:
- API keys, tokens, or passwords in client-side code
- .env files committed to git
- Hardcoded URLs to production services
- Secrets in comments or console.log statements

## Step 2: Verify Auth & Authorization
- Check that all API endpoints require authentication
- Verify Row Level Security policies on all Supabase tables
- Ensure auth tokens are stored securely (not AsyncStorage plaintext)
- Check for proper session expiry handling

## Step 3: Input Validation
- Check all user inputs are validated before use
- Look for SQL injection, XSS, and command injection vectors
- Verify file upload restrictions (type, size)

## Step 4: Report
Generate a report with:
- CRITICAL: issues that must be fixed before shipping
- WARNING: issues that should be fixed
- INFO: suggestions for improvement

For each issue, show the file, line, and a fix.

When you type /security-audit, Claude Code reads this file and executes each step against your actual codebase. It finds real vulnerabilities, shows you exactly where they are, and suggests fixes.

Compare this to just asking Claude Code "check my code for security issues" — without the structured skill, it will give you a generic overview. With the skill, it follows a systematic checklist and catches things it would otherwise miss.

DIY vs Pre-Built Skills

You can absolutely write your own skills. For project-specific tasks — like "deploy to staging" or "run the test suite" — custom skills make total sense.

But for complex, multi-step workflows like idea validation, frontend generation, payment integration, or ASO optimization — the skills need to encode deep domain knowledge. They need to know:

• What questions to ask (and in what order)
• What data to pull and where to find it
• What patterns work and what patterns fail
• How to handle edge cases you haven't thought of
• What the output should actually look like

This is where pre-built skills save you months of trial and error.

How SkillDeck Uses Skills Files

SkillDeck is a collection of 20 pre-built skills that cover the entire app-building pipeline — from finding an idea to scaling revenue. Each skill is a SKILL.md file that you drop into your project's .claude/skills/ directory.

What makes SkillDeck skills different from a skill you'd write yourself:

• Deep interview process — each skill asks 5-15 targeted questions before generating anything. Your answers shape every decision the skill makes.
• Real market data — skills like /find-idea and /validate-idea scan Reddit, App Store data, and Google Trends for actual demand signals.
• Built on experience — every skill encodes lessons from $600K in app revenue, 150+ viral app teardowns, and 7 shipped apps.
• Pipeline architecture — each skill hands off to the next. /plan-app generates a CLAUDE.md that /frontend and /backend use automatically.

The 20 skills cover:

Getting Started with Skills Files

Whether you write your own or use pre-built ones, here's how to get started:

Step 1: Create a CLAUDE.md for your current project

Open your project, create a CLAUDE.md file in the root, and write a brief description of your app, tech stack, and coding rules. Even 10 lines will dramatically improve Claude Code's output.

Step 2: Try writing a simple skill

Create .claude/skills/code-review/SKILL.md with a simple code review checklist. Run /code-review and see how Claude Code follows your structured instructions versus an ad-hoc prompt.

Step 3: Scale with pre-built skills

Once you see the difference structured skills make, you'll want them for everything — idea validation, frontend generation, security audits, App Store optimization. This is where a curated skill library saves you from writing (and debugging) 20 skills yourself.

The Bottom Line

Skills files are the most underrated feature of Claude Code. They turn a conversation-based AI into a structured workflow engine. Instead of hoping you write the right prompt, you encode your process once and get consistent, high-quality output every time.

The developers who figure this out early have an enormous advantage — they ship faster, with fewer bugs, and with better results than people treating Claude Code like a fancy chatbot.

Building in public and sharing what I learn on X. Follow along if you're interested in AI coding, app building, and what's actually working right now.