How to Create a Claude Code Skill from Scratch

What is a skill, exactly?

A Claude Code skill is a folder containing a SKILL.md file that pre-loads Claude with a specialized behavior. When Claude reads the skill at startup, it knows: what this skill handles, how to handle it, and what the output should look like.

Skills aren't plugins. They don't add new capabilities at the runtime level — they encode your workflow knowledge into Claude's context. Claude already knows how to write code, parse files, and reason about problems. A skill tells it specifically how to do those things for your particular use case.

Skill vs. just prompting

Build a skill when all of these are true:

You run the same complex workflow more than a few times a week
The workflow has specific steps, constraints, or output formats Claude wouldn't know without instructions
You're tired of re-explaining the same context every session

If it's a one-off task or a simple prompt, don't bother with a skill. The overhead isn't worth it. Skills pay off for things like: audit checklists, domain-specific code generation, structured output formats, or any multi-step workflow with a defined shape.

Step 1: Define the problem

Before writing a single line of SKILL.md, answer these three questions:

What specific task does this skill handle? Be precise. "Helps with SQL" is not a task. "Converts a plain-English data model description into a Postgres schema with migrations" is a task.
Who uses it, and what do they bring? What input does the user provide? A description? A list of files? A raw dump?
What does the output look like? A file? A report? A series of SQL statements? Define the shape before you write the instructions.

Write these down. The answers become your SKILL.md's description and instruction body.

Step 2: Write SKILL.md

Create the skill folder and the file:

Terminal

$ mkdir -p ~/.claude/skills/my-skill
$ touch ~/.claude/skills/my-skill/SKILL.md

Frontmatter: the fields that matter

The YAML frontmatter at the top of SKILL.md controls how Claude identifies and invokes the skill:

---
name: Schema Sketcher
description: >
  Converts a plain-English description of what data you need to store
  into a Postgres schema with CREATE TABLE statements and migrations.
  Includes sensible column types, NOT NULL constraints, and index suggestions.
version: 1.0.0
author: your-name
---

The description is what Claude reads to decide whether to invoke this skill. It should include the trigger phrase — the kind of thing a user would say when they need this skill. If the user says "I need to store user sessions and I want a Postgres schema," Claude should match that to a skill that mentions Postgres schemas.

Vague descriptions like "helps with databases" will miss triggers. Specific descriptions with the task, the input type, and the output type will catch the right requests.

Instructions: what Claude actually does

Below the frontmatter, write the instructions in plain Markdown. Structure them as a clear workflow:

## Workflow

1. Ask the user to describe the data they want to store in plain English, if they haven't already.
2. Identify the entities (tables) and their relationships from the description.
3. For each entity, define columns with appropriate Postgres types.
4. Add primary keys as `id UUID DEFAULT gen_random_uuid() PRIMARY KEY`.
5. Add `created_at TIMESTAMPTZ DEFAULT NOW()` and `updated_at TIMESTAMPTZ DEFAULT NOW()` to every table.
6. Write the `CREATE TABLE` statements.
7. Write a migration file in the format: `YYYYMMDD_create_entity_name.sql`.
8. Suggest indexes for any foreign keys and frequently-queried columns.

## Limitations

- This skill generates schemas for Postgres only. If the user mentions MySQL or SQLite, flag it.
- Do not generate stored procedures or triggers unless explicitly requested.
- If the description is ambiguous, ask one clarifying question before proceeding.

Adding examples

Examples are optional but powerful. If you include an example input and expected output, Claude uses it as a reference for the pattern it should produce:

## Example

**Input:** "I need to store blog posts. Each post has a title, body, an author, and can have multiple tags."

**Output:**
```sql
CREATE TABLE authors (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  name TEXT NOT NULL,
  email TEXT NOT NULL UNIQUE,
  created_at TIMESTAMPTZ DEFAULT NOW()
);
-- ... rest of schema
```

Step 3: Add optional support files

If your skill needs helper scripts or long reference documents, add them now:

scripts/ — shell or Python scripts Claude can tell you to run, or can invoke directly
references/ — long docs the instructions can point to (e.g., a list of required environment variables)
templates/ — output templates for consistent formatting

Reference these from SKILL.md by relative path: See `references/postgres-types.md` for the full type reference.

Step 4: Test the skill

Restart Claude Code after installing the skill, then try triggering it with natural language. Don't name the skill explicitly — just describe what you want:

"I need a Postgres schema for a multi-tenant SaaS with organizations, users, and workspaces."
"Convert this data model description to a database schema."

If Claude doesn't invoke the skill, check the description. It's almost always a description mismatch. The trigger phrase in the description needs to match how users naturally ask for this thing.

Step 5: Iterate

After testing with a few real inputs, you'll find gaps. Common issues:

Instructions too long: Claude can lose track in a very long SKILL.md. Keep the core workflow under 400 words. Move reference material to references/.
Instructions too vague: If Claude is generating generic output, your instructions need more specificity about the expected format.
No examples: Adding one good example often fixes consistency problems immediately.
Description too broad: A broad description triggers the skill when it shouldn't. Narrow it by adding "only when" constraints.

Common mistakes

Describing what the skill is instead of what it does. "A skill for SQL" tells Claude nothing useful. "Generates Postgres CREATE TABLE statements from plain-English data model descriptions" tells Claude exactly when to use it.

Writing instructions for Claude to read literally. Claude interprets instructions, it doesn't execute them like code. Write clearly, but don't try to write pseudo-code or use special syntax — plain Markdown prose is what works.

Not including a Limitations section. Telling Claude when not to use the skill (or what to do when the input is ambiguous) prevents bad outputs.

Once you're happy with the skill, ZIP the entire skill folder and share it. Anyone can install it by unzipping into their ~/.claude/skills/ directory.