Your First Claude Code Skill in 10 Minutes

Summary:

1. Build a working SKILL.md file that changes Claude’s output in 10 minutes.
2. Learn the four-part anatomy: trigger, instructions, constraints, examples.
3. Get a complete code-style skill with before/after TypeScript output.
4. Copy-paste the verification checklist when your skill won’t load.

You open Claude Code. You ask it to write a function. It uses var, adds semicolons you don’t want, default exports you banned last month, and names the variable data. You correct it. Tomorrow, you correct it again. Every session starts from zero.

Three weeks after I built my first skills library, Claude stopped asking me what coding style I preferred. It stopped suggesting Express when my project uses Fastify. It stopped writing tests in Jest when my repo uses Vitest. I hadn’t changed anything about how I prompted it. I changed what it knew before I opened my mouth.

One markdown file in the right folder. Here’s how to build yours.

What is a Claude Code skill?

A skill is a persistent markdown file that changes how Claude writes code for your project. It loads before your first message in every session. Unlike prompts you type in chat, skills survive between sessions. Unlike custom instructions, skills are modular: you can have 50 of them, each handling one concern.

Think of skills like ESLint configs for Claude. ESLint catches violations after code is written. Skills prevent violations before code is produced. Claude reads the rules, then writes code that follows them.

your-project/
  .claude/
    skills/
      code-style.md    ← project skill (this project only)
  src/
  package.json

~/.claude/
  skills/
    stop-slop.md       ← global skill (every project on your machine)

Project-level skills live in .claude/skills/. Global skills live in ~/.claude/skills/. Project skills override globals when they conflict. Start with project-level. Go global later once you have a personal style you want everywhere.

How do you create a skill file?

You create a skill by making a .md file in .claude/skills/ at your project root.

Step 1: Create the directory.

mkdir -p .claude/skills

Step 2: Create .claude/skills/code-style.md with four sections:

# Code Style

## Trigger
Always active for this project.

## Instructions
- Use TypeScript with strict mode enabled
- Use 2-space indentation, no tabs
- Use single quotes for strings
- Add trailing commas in multi-line objects and arrays
- Use arrow functions for callbacks and inline functions
- Use named exports, not default exports
- Import order: external packages first, then internal modules,
  then relative imports, with a blank line between each group
- File names use kebab-case (e.g., user-service.ts)

## Constraints
- Never use the `any` type. Use `unknown` if the type is truly unknown.
- Do not use `var`. Use `const` by default, `let` only when needed.
- Do not add semicolons. This project uses no-semicolon style.

## Example
Bad:
  import { UserService } from "./UserService";
  var data: any = await fetch(url);

Good:
  import { z } from 'zod'

  import { createUser } from '../models/user'
  import { validate } from './helpers/validation'

  const data: unknown = await fetch(url)

That’s 30 lines. Took 3 minutes.

Step 3: Save the file and open Claude Code in your project.

Step 4: Ask Claude to write a function: “Write a function that fetches a user by ID and returns their profile.”

What changes after adding the skill?

Night and day.

Without the skill:

import UserService from "./UserService"

export default async function getUser(id: any) {
  var user = await UserService.findById(id);
  return user;
}

Generic names. any type. var. Default export. Semicolons. Every line needs correction.

With the skill loaded:

import { z } from 'zod'

import { findById } from '../services/user-service'

const userIdSchema = z.string().uuid()

export const getUser = async (id: string) => {
  const validId = userIdSchema.parse(id)
  const user = await findById(validId)
  return user
}

No any. No var. No default export. No semicolons. Arrow function. Correct import ordering. Kebab-case filename reference. Every instruction from the skill reflected in the output. You didn’t change your prompt. You changed one file.

What makes a skill work vs. fail?

Specificity. That’s the whole game. I tested vague skills on three different codebases. No measurable difference in output.

This skill does nothing:

# Code Quality
## Instructions
- Write clean, maintainable code
- Follow best practices
- Make sure the code is well-organized
- Use appropriate design patterns

Every instruction is subjective. Claude’s definition of “clean” is not your definition. The skill loads, Claude reads it, output changes by zero percent.

This skill changes everything:

# Code Quality
## Instructions
- Functions must be under 30 lines. If longer, extract a helper.
- No more than 3 parameters per function. Use an options object
  for anything beyond 3.
- All conditionals with more than 2 branches use early returns,
  not nested if/else.
- Variable names must include the unit for numeric values:
  durationMs, distanceKm, priceUsd.

Every rule is binary. Either the function is under 30 lines or it isn’t. Either the variable includes the unit or it doesn’t. Claude follows binary rules with near-perfect accuracy. It struggles with subjective guidance.

The test: For every rule in your skill, ask: “Could I write a lint rule that checks this?” If yes, the rule is specific enough. If no, rewrite it.

The community has already figured this out. The awesome-claude-skills repo on GitHub (47.9k stars) collects 70+ community-contributed skills across 9 categories. The skills that actually get used and shared follow this pattern: specific, binary, testable. The ones that rot in someone’s folder are “write clean code” type instructions.

For the official reference on how skills load and activate, see Anthropic’s skills documentation.

What broke (and how to fix it)

Your skill exists but Claude ignores it. This happens to everyone. Run through these five checks in order.

Check 1: File location. Skills must be in .claude/skills/ at the project root. Not .claude/ directly. Not skills/ without the parent.

# Verify your skill file exists in the right place
ls -la .claude/skills/

Check 2: File extension. The file must end in .md. One developer’s editor saved files as .md.txt with the real extension hidden by the OS. Claude saw .txt files and ignored them all.

# Check real extensions (catches hidden .txt suffix)
ls -la .claude/skills/*.md

Check 3: Session freshness. Close Claude Code and reopen it. Some versions cache skills at session start.

Check 4: Verification test. Ask Claude directly: “What coding style rules are you following for this project?” A skill-aware Claude responds with your specific rules:

You: What coding style rules are you following?

Claude: Based on the code-style skill loaded for this project:
- TypeScript with strict mode
- 2-space indentation, no tabs
- Single quotes, no semicolons
- Named exports only (no default exports)
- Import order: external → internal → relative
- kebab-case filenames

If Claude gives generic advice instead of your rules, the skill didn’t load. Go back to checks 1-3. If it lists your rules but output doesn’t follow them, the rules are too vague (see the good vs. bad skill examples above).

Check 5: Permissions. Run cat .claude/skills/code-style.md in your terminal. If you can read it, Claude can read it.

How do you pick what to put in your first skill?

Don’t start with testing. I tried that. The feedback loop is slow because you have to generate code, then tests, then check both. Start with code style. You already know what your code should look like. You’ve corrected Claude on formatting before. The instructions come from memory, and you’ll see the difference in 30 seconds.

Three other good first skills if code style doesn’t fit:

Skill	Trigger	One rule that matters
Commit messages	When creating commits	type(scope): description format, max 72 chars
Testing standards	When writing tests	Assert on specific values, never truthiness
Documentation	When writing source files	JSDoc on exports only, skip private helpers under 10 lines

Pick one. Build it. Test it. Five minutes each. By the end of a week, you’ll have rules that make Claude’s output match your project on the first try.

What should you actually do?

• If you’ve never built a skill: create the code-style skill from this article. Test it with one function request. Takes 10 minutes.
• If you have a skill but it’s not working: run through the 5-check diagnostic above. The fix is almost always file path or extension.
• If your skill works but output is inconsistent: add a before/after ## Example section. Claude anchors on examples more reliably than abstract rules.

bottom_line

• One markdown file in .claude/skills/ changes Claude’s behavior across every session. No prompting, no reminders, no copy-paste.
• Specificity is the only thing that matters. “Use 2-space indentation” works. “Write clean code” does nothing.
• Your first skill should take 10 minutes. If it takes longer, you’re overcomplicating it. Start with 15 specific rules, use it for a week, let the gaps reveal themselves.