What is Skill.md?

The short answer

A Skill.md is a structured Markdown file that packages domain knowledge into a format Claude Code agents can load on demand. Think of it as a specialist briefing doc: instead of prompting Claude with three paragraphs of context every time you need it to write a database migration, you write that context once, save it as a skill, and the agent picks it up automatically when the task matches.

Skills live in ~/.claude/skills/ (user-level) or .claude/skills/ (project-level). Claude Code reads the skill's description field to decide whether to load it for any given task.

What's inside a Skill.md file

Every skill has the same four-part structure:

---
name: Database Migration Expert
description: Use when writing, reviewing, or debugging
           SQL migrations for PostgreSQL or MySQL.
---

# Overview
Why this skill exists and when to apply it.

## Key patterns
Concrete examples of what to do and how.

## Pitfalls
Common mistakes and how to avoid them.

## Reference
Tables, schemas, command references.

How it's different from a system prompt

System prompts are always loaded — they consume context tokens whether the task needs them or not. Skills are loaded on demand. When you start a task, Claude Code checks every skill's description and loads only the ones relevant to what you're doing.

This matters for two reasons:

• Context efficiency. A codebase with 20 skills doesn't mean 20× more tokens per request. Most tasks load 1–3 skills.
• Composability. Skills stack. A task touching both a database and an API can load both the "database migrations" skill and the "REST API design" skill simultaneously.

How is Skill.md different from CLAUDE.md?

CLAUDE.md is always-on project or user configuration — it sets conventions, gives Claude persistent context about a repo, and overrides default behavior. It is not selective.

Skill.md is domain expertise loaded on demand. Use CLAUDE.md for "always remember this about our project." Use Skill.md for "when doing X, apply this specialised knowledge."

A real example

Here's a minimal but functional Skill.md for a SaaS SEO specialist:

---
name: SaaS SEO Playbook
description: Use when planning SEO strategy, writing meta
           tags, building content clusters, or auditing
           technical SEO for a SaaS product.
---

# Overview
Keyword strategy for SaaS prioritises BOFU terms
(alternatives, comparisons, pricing) before TOFU
volume plays. Recurring-revenue context changes
everything about how you score opportunities.

## Key patterns
### Keyword scoring matrix
| Factor            | Weight |
|-------------------|-------:|
| Conversion intent |    30% |
| Keyword difficulty|    25% |
| Search volume     |    20% |
| Content gap       |    15% |
| Business relevance|    10% |

## Pitfalls
- Prioritising search volume over conversion intent
- Publishing isolated posts instead of content clusters

When you ask Claude to "plan our content strategy for Q3," it loads this skill automatically and applies the BOFU-first framework — no prompting required.

How to create a Skill.md

You have two options:

1. Write it by hand. Use the structure above. Works well if you already have the expertise and just need to encode it.
2. Generate it from a source article. Paste any URL into Skillify and it extracts patterns, pitfalls, and reference material automatically — takes about 30 seconds.