Getting Started with Claude Code Skills

You’re getting value from Claude Code. It’s part of your workflow now. But there’s a gap between “this is useful” and “this understands my codebase.”

You want to close that gap — without adopting a new system, changing how your team works, or risking delivery while you experiment. You still need to ship features, and quietly improving your own workflow has to fit inside that reality.

So what’s the smallest step you can take that makes Claude Code work better for your codebase, without disrupting what’s already working?

Skills: Teach Claude One Thing at a Time

Claude Code skills are small, opt-in markdown files that you invoke on demand to give Claude targeted context for a specific task.

Think of a skill as a short internal guide — the kind you’d write for a teammate — but optimized for Claude.

Why this works well for incremental adoption:

• Opt-in: You invoke a skill only when it’s relevant. Nothing changes unless you ask for it.
• Per-task: Skills provide focused context for a specific situation, not global rules for everything.
• Additive: Start with one skill. Add another when you notice a pattern. No big-bang changes.

Instead of trying to teach Claude everything about your codebase at once, you teach it one thing at a time — the things you’re already correcting anyway.

Your First Skill: Pick One Pain Point

What’s something Claude consistently gets wrong in your codebase?

That’s your first skill.

Common examples:

• Which API client to use (you have three, only one is current)
• How tests are structured (you have conventions it doesn’t know)
• Where new components should live (your folders mean something)

If it’s something you can explain in a few paragraphs, it’s a good first skill.

Example: A “Patterns” Skill

Imagine a frontend codebase that’s evolved over time. There are three ways to make API calls:

1. Raw fetch calls from the early days
2. A hand-rolled api.js utility from the first refactor
3. The current standard: React Query with a typed API client

Your team knows to use option 3. Claude doesn’t — it sees all three patterns and may reach for any of them.

Create a skill to make the preference explicit.

First, create a skills directory:

mkdir -p .claude/skills

Then add a new file:

.claude/skills/patterns/SKILL.md

---
name: patterns
description: Defines which API patterns are current and preferred in this codebase. Use when writing or modifying API-related code where multiple legacy patterns exist.
---

# Codebase Patterns

When implementing features, prefer current patterns over deprecated ones.

## API Calls

### Current: React Query + apiClient

Use React Query with our typed API client for all new code:

import { useQuery, useMutation } from '@tanstack/react-query';
import { apiClient } from '@/lib/api-client';

// Fetching
const { data, isLoading } = useQuery({
queryKey: ['users', userId],
queryFn: () => apiClient.get(`/users/${userId}`)
});

// Mutations
const mutation = useMutation({
mutationFn: (data: CreateUserInput) => apiClient.post('/users', data),
onSuccess: () =>
queryClient.invalidateQueries({ queryKey: ['users'] })
});

The apiClient handles auth tokens, base URL, and error transformation.

### Deprecated: api.js utility

You’ll see this in older code:

import { get, post } from '@/utils/api';
const users = await get('/users');

Don’t use for new code. It lacks proper error handling and doesn’t integrate
with React Query caching.

### Deprecated: Raw fetch

The oldest pattern. Don’t use — it bypasses all API infrastructure.

Using the Skill

Close and restart Claude Code. The skill will be used automatically based on the description provided in the frontmatter.

Add a new endpoint to fetch user preferences

Claude now knows which pattern to use. Nothing else changes — you still describe the task the same way you always do.

You can also reference the skill in your CLAUDE.md:

When working on features involving API calls, run `/patterns` first.

This keeps the guidance discoverable without enforcing anything globally.

What’s Next

When you notice something else Claude keeps getting wrong, capture it.

Examples:

• /testing — Your test conventions and helpers
• /components — Where components go and how they’re structured
• /errors — How errors are created, wrapped, and reported

Each addition is small. A few minutes to write — and you never have to correct that thing again.

The Compounding Effect

Every skill makes Claude more effective in your codebase specifically. Not in the abstract — in the messy, evolved, real code you actually work in.

This is the incremental path forward: start with one pain point, teach Claude about it, and move on with your day.

No new system. No disruption. Just one small improvement you can use immediately.