Building a Claude Code skill from scratch — the complete guide

We've reviewed hundreds of skills for RuleSell's marketplace. Most fail for the same three reasons: the description doesn't trigger when users need it, the skill loads too much context, or it tells Claude things Claude already knows. This guide exists to fix all three.

By the end, you'll have a working skill with proper frontmatter, progressive disclosure, a reference file, and a validation step. We're using a real example — a database migration skill for Prisma — because abstract guidance produces abstract output.

How skills actually work (the 30-second version)

A Claude Code skill is a directory containing a SKILL.md file. At startup, Claude sees only the name and description from your frontmatter — about 250 characters per skill. When Claude's language model decides your skill matches the user's intent, it reads the full SKILL.md. If your skill references other files, Claude reads those on demand.

This is progressive disclosure: the skill system shows Claude just enough to decide, then reveals more as needed. A deep dive by Lee Han Chung confirmed the mechanics — skill names and descriptions are pre-loaded into the system prompt (approximately 15,000 characters budget across all skills), and the full SKILL.md loads only on invocation.

The practical implication: your description is an ad for your skill. If the description doesn't convince Claude to load the skill, the skill's content never runs. And once loaded, every token in SKILL.md competes with the conversation history, other skills, and the user's request.

Step 1: Choose the right scope

Before writing anything, decide what your skill covers. The most common failure mode is skills that are too broad.

"Helps with database stuff"

"Runs prisma migrate deploy on production PostgreSQL databases running on Supabase"

"Creates and runs Prisma database migrations including schema changes, data 
migrations, and rollbacks. Use when the user asks to add or change a database 
table, create a migration, modify a Prisma schema, or needs to roll back a 
failed migration."

The formula from Anthropic's skill authoring guide: What it does + When to use it + Key capabilities. Write in third person ("Creates and runs..." not "I can help you..."), because the description is injected into the system prompt and first-person creates confusion.

Step 2: Create the directory structure

Skills live in one of three places:

mkdir -p ~/.claude/skills/prisma-migrate
mkdir -p ~/.claude/skills/prisma-migrate/references

The directory structure will be:

prisma-migrate/
├── SKILL.md              # Main instructions (loaded on trigger)
├── references/
│   ├── migration-types.md  # Loaded when Claude needs migration details
│   └── rollback-guide.md   # Loaded only for rollback scenarios

Step 3: Write the frontmatter

The YAML frontmatter between --- markers controls discovery and behavior. Here's what each field does:

---
name: prisma-migrate
description: >-
  Creates and runs Prisma database migrations including schema changes,
  data migrations, seed scripts, and rollbacks. Use when the user asks
  to add, change, or remove database tables or columns, create a migration,
  modify a Prisma schema, resolve migration drift, or roll back a failed
  migration. Not for raw SQL queries or non-Prisma ORMs.
allowed-tools: Bash(npx prisma ) Read Grep Glob Edit
---

Other frontmatter options worth knowing

# Prevent Claude from auto-triggering (user must type /prisma-migrate)
disable-model-invocation: true

# Run in isolated subagent context context: fork agent: Explore

# Limit to projects that have Prisma paths: "/prisma/schema.prisma"

The paths field is underused and powerful. Setting paths: "/prisma/schema.prisma" means Claude only loads this skill when working with files in a project that has a Prisma schema. No false triggers on non-Prisma projects.

Step 4: Write the SKILL.md body

The body is the prompt Claude receives when the skill activates. The official guidance says keep it under 500 lines. We aim for under 100 in the main file, pushing details to references.

---
name: prisma-migrate
description: >-
  Creates and runs Prisma database migrations including schema changes,
  data migrations, seed scripts, and rollbacks. Use when the user asks
  to add, change, or remove database tables or columns, create a migration,
  modify a Prisma schema, resolve migration drift, or roll back a failed
  migration. Not for raw SQL queries or non-Prisma ORMs.
allowed-tools: Bash(npx prisma *) Read Grep Glob Edit


# Prisma Migration Workflow

Before any migration

Read the current schema: prisma/schema.prisma
Check migration status: npx prisma migrate status
If drift detected, resolve before proceeding
Creating a migration

Edit prisma/schema.prisma with the requested changes
Run: npx prisma migrate dev --name <descriptive-name>
Review the generated SQL in prisma/migrations/
If the migration includes data loss (dropping columns/tables),
   warn the user explicitly before proceeding

Migration naming

Use descriptive kebab-case names that explain the change: 
add-user-email-verification
remove-legacy-auth-columns
create-order-items-table
 Never use generic names like update or fix.


Data migrations

For migrations that need to transform existing data, create a separate migration script. See references/migration-types.md for the three migration patterns (schema-only, data-transform, seed).

Rollbacks

If a migration fails or needs reverting: See references/rollback-guide.md

Validation

After every migration:

 If either command fails, fix the issue before marking the task complete. Do not skip validation.

Notice what we're doing:

1. Concrete commands — not "run the migration tool" but npx prisma migrate dev --name
2. Progressive disclosure — migration types and rollback details live in reference files, loaded only when needed
3. Validation loop — the skill ends with a verification step that forces Claude to confirm success
4. Opinionated naming — we tell Claude exactly how to name migrations instead of letting it decide
5. Safety rail — explicit warning requirement before data-loss migrations

Step 5: Write the reference files

Reference files contain the detail that would bloat SKILL.md. Claude reads them only when the conversation requires it.

# Prisma Migration Types

Schema-only migration
Changes the database schema without touching existing data.

Example: adding a new optional column.

 Run: npx prisma migrate dev --name add-user-bio


Data-transform migration

Changes schema AND needs existing data moved or transformed.

Example: splitting a name field into firstName and lastName.

Steps: 
Add new columns (nullable): npx prisma migrate dev --name add-name-fields
Write a data script to populate new columns from old:

3. Make new columns required, drop old: npx prisma migrate dev --name finalize-name-split


Always do this in multiple migrations, not one. Each step is independently reversible.

Seed migration

Populates reference data (countries, categories, roles) that the app needs to function.

Run after migration: npx prisma db seed

Seed scripts live in prisma/seed.ts (or seed.js).

# Prisma Migration Rollback

Development (local database)

Reset and replay:

 This drops the database, recreates it, and replays all migrations. Only use in development. Never in production.


Production

Prisma does not have a built-in rollback command for production. Options:

Forward migration: Create a new migration that undoes the changes.
   This is the safest approach and creates a clear audit trail.

Manual SQL: Write reversal SQL and apply with:

Resolve and mark: If a migration partially applied:

After any rollback

Run npx prisma migrate status to verify state
Run npx prisma validate to check schema consistency
Run npx prisma generate to regenerate the client
Always verify the application starts and passes tests after rollback.

"I need to add an email verification field to the User table"
"Create a migration for the new orders feature"
"The last migration failed, help me roll it back"

"Write a raw SQL query to count users"
"Help me set up a MongoDB connection"
"What's the best ORM for Go?"

Prisma is an ORM (Object-Relational Mapping) tool that helps developers interact with databases using a type-safe query API...

You can use prisma migrate dev, or prisma db push, or write raw SQL, or use a third-party migration tool...

Use prisma migrate dev for all migrations. Use prisma db push only for prototyping (warn the user it skips migration history).

~/.claude/skills/prisma-migrate/
├── SKILL.md                        # 45 lines of frontmatter + instructions
├── references/
│   ├── migration-types.md          # ~50 lines, loaded on demand
│   └── rollback-guide.md           # ~40 lines, loaded on demand