How to create Claude skills

Before you start

Claude Code loads skills from two locations. Pick the right one before you create the file:

• ~/.claude/skills/ — user-level skills, available in every project on your machine
• .claude/skills/ — project-level skills, checked into the repo, shared with the team

If the skill captures knowledge that's relevant beyond one codebase (e.g. "how to write good SQL migrations"), put it at user level. If it encodes knowledge specific to your product or stack (e.g. "our API versioning conventions"), put it in the project.

The five steps

1. Choose the domain

   Pick a specific, bounded area of expertise. The tighter the scope, the more reliably Claude loads the skill at the right moment. "Backend development" is too broad. "Writing database migrations for PostgreSQL with zero-downtime patterns" is right.

2. Write the frontmatter

   The description field is what Claude reads to decide whether to load the skill. Write it as a trigger condition, not a summary.

   ---
   name: PostgreSQL Migration Expert
   description: Use when writing, reviewing, or debugging
              PostgreSQL migrations, especially those that
              need to run on tables with millions of rows.
   ---

   Tip: Start the description with "Use when…" — it frames the text as a condition rather than a label, which tends to produce more reliable loading.

3. Write the key patterns section

   This is the core of the skill. Include:

   • Decision rules ("if X, do Y")
   • Concrete code examples
   • Reference tables (commands, flags, options)
   • Context the agent wouldn't have from the code alone

   Don't summarise what Claude already knows from training. Only add knowledge that's project-specific, opinionated, or non-obvious.

4. Add a pitfalls section

   Show bad vs. good comparisons for the most common mistakes. Claude uses these to self-correct during generation.

   ## Pitfalls
   
   ### Adding NOT NULL columns without a default
   
   Bad:
     ALTER TABLE users ADD COLUMN plan TEXT NOT NULL;
     -- Fails immediately on non-empty tables
   
   Good:
     -- Step 1: add nullable
     ALTER TABLE users ADD COLUMN plan TEXT;
     -- Step 2: backfill
     UPDATE users SET plan = 'free' WHERE plan IS NULL;
     -- Step 3: add constraint
     ALTER TABLE users ALTER COLUMN plan SET NOT NULL;

5. Save and test

   Save the file to the correct location, then trigger it with a matching task in Claude Code. Check that the agent applies the patterns from your skill, not generic behaviour.

   # Save to user-level skills
   cp my-skill.md ~/.claude/skills/postgres-migrations.md
   
   # Or project-level
   cp my-skill.md .claude/skills/postgres-migrations.md

   If the skill isn't loading, check that the description clearly describes what you're asking Claude to do. The description match is fuzzy but the trigger condition needs to be unambiguous.

What makes a good skill description

The description field is the most important part of the file. Here are examples of weak vs. strong descriptions:

The shortcut: generate from a source

Writing a skill from scratch takes 30–90 minutes for a well-structured domain. If there's already a good article, spec, or documentation page that covers the domain, you can skip most of that work.

Paste the URL into Skillify and it extracts the key patterns, pitfalls, and reference material automatically — producing a correctly-structured Skill.md in about 30 seconds. You'll still want to review and customise the output, but it gives you a complete draft to edit rather than a blank file.