Say you have a workflow you run all the time - writing blog posts, reviewing PRs, starting a new session. Without skills, you’re re-explaining that workflow to Claude every time. With a skill, you write it down once in a file, and Claude follows it whenever you need it - either when you type /skill-name or automatically when it recognizes what you’re doing.

WHAT SKILLS ARE

A skill is a text file with instructions for Claude. Each one lives in its own folder with a SKILL.md file inside it, either in your project (.claude/skills/) or globally (~/.claude/skills/ for workflows you use across all projects).

THE MENTAL MODEL CLAUDE.md is house rules everyone follows all the time. Skills are instruction manuals you pull off the shelf when needed. House rules say “no shoes indoors.” The instruction manual says “here’s how to assemble the bookshelf.”

You can type /skill-name to invoke one manually, but skills can also activate on their own when Claude reads your message and decides a skill is relevant. At startup, Claude only loads the name and description of each skill. The full instructions load when a skill actually activates, so having 20 skills sitting there doesn’t slow anything down.

SKILL VS CLAUDE.MD

I kept stuffing everything into CLAUDE.md until it was 200+ lines and Claude was parsing my entire content workflow, design system rules, and session rituals on every single message.

CLAUDE.md = things that apply to every conversation:

  • Project structure, tech stack, coding standards
  • Rules that never change (“always use design tokens”, “never commit to main”)
  • Short and tight, ideally under 150 lines

Skills = repeatable, chainable instructions for specific tasks:

  • “When I say /article, walk me through my whole content workflow”
  • “When I ask about the backlog, check these files and report back”
  • “When reviewing code, follow this checklist and only read, don’t edit”

If it applies to every conversation, CLAUDE.md. If it applies to a specific type of task, skill.

SKILL STRUCTURE

Every skill is a folder with a SKILL.md file. The folder can also include whatever reference material helps Claude do the job - templates, brand guidelines, example files, images, scripts, whatever is relevant to the workflow:

.claude/skills/
└── content-pipeline/
    ├── SKILL.md              # Main instructions (required)
    ├── voice-guidelines.md   # Writing style reference
    ├── brand-assets/
    │   └── logo-specs.png    # Brand reference Claude can see
    └── scripts/
        └── post-status.sh    # Script Claude can run

Claude loads these supporting files on demand, not all at once, so you can include as much reference material as you need without worrying about bloat.

The SKILL.md itself has two parts. The top section between the --- lines is metadata that tells Claude the skill’s name and when to use it. Everything below is the actual instructions.

---
name: content-pipeline
description: Manages blog content pipeline including drafts, scheduled posts, and backlog. Use when discussing content status, scheduling, or asking what to write next.
---

## Instructions for Claude go here...

WHAT’S FRONTMATTER The section between the --- lines at the top of a file is called “frontmatter.” It’s just structured metadata - name, description, settings. Claude Code reads it to understand what the skill is before deciding whether to load the full instructions.

The description is the most important line. Claude reads it to decide whether to load the skill, and vague descriptions mean Claude skips your skill entirely.

MAKING SKILLS MORE POWERFUL

The basics get you pretty far, but skills have some advanced features that unlock a lot more if you need them:

Invocation control lets you decide who can trigger a skill. By default both you and Claude can, but you can lock it to user-only (disable-model-invocation: true) if you don’t want Claude auto-loading it, or Claude-only (user-invocable: false) for background knowledge that kicks in silently.

Context forking runs the skill in its own separate conversation. Add context: fork to the frontmatter and the skill executes in a subagent with its own context window. The heavy lifting happens off to the side and a summary comes back to your main conversation. Good for research-heavy skills where you don’t want all that output cluttering your main conversation.

Dynamic context injection lets your skill run shell commands before Claude even sees the instructions. Use the !`command` syntax and the output replaces the placeholder:

---
name: pr-review
description: Review the current pull request
---
## Current diff
!`gh pr diff`

Review for code quality issues.

When you invoke /pr-review, Claude sees the actual diff content, not the shell command. Your skill can pull in live git status, test results, file listings, whatever you’d normally run in the terminal.

Tool restrictions scope what Claude can do during a skill. Add allowed-tools: Read, Grep, Glob to the frontmatter and Claude can use those tools without asking permission, while other tools require approval. Useful for review skills where you mostly want read-only behavior.

WHY COMPANIES ARE RELEASING SKILLS

You might have seen Figma, Vercel, Stripe, and others announcing Claude Code skills recently. This is a big deal for a simple reason: these companies are packaging their own expertise into skills that make Claude way better at using their products than it would be on its own.

Without a Vercel skill, Claude knows how to deploy stuff to Vercel in a general sense. With Vercel’s official skill installed, Claude knows Vercel’s current APIs, best practices, edge cases, and recommended patterns. The difference is like asking someone who read about a restaurant vs someone who works there.

This is why people were so excited about MCPs last year (connecting Claude to external services), and now skills are getting the same energy, because they let anyone - companies, communities, individuals - package up knowledge and workflows that make Claude meaningfully better at specific things.

Type /plugin to browse what’s available. Anthropic maintains an official directory with partner-built skills, and there are community marketplaces with hundreds more you can add with /plugin marketplace add. I wrote about the whole plugin system if you want the full picture.

BUILDING YOUR FIRST SKILL

Start with something you actually do repeatedly. A session start ritual is a good first one. Just tell Claude what you want:

Create a skill called session-start in .claude/skills/ that:
1. Reads CLAUDE.md for project context
2. Checks TODO.md for current tasks
3. Shows me what's in progress
4. Asks what I want to work on today

Write a clear description so the skill shows up when I type /session-start.

Claude creates the directory, writes the SKILL.md, and you’ve got a repeatable workflow. For more on the gotchas - description formatting that silently breaks, trigger words Claude ignores - I wrote about all the ways my first skill refused to work.

WHERE SKILLS WORK

Skills aren’t just a Claude Code thing. They work across Claude’s products, though the setup is different depending on where you are:

  • Claude Code - File-based. Drop skills into .claude/skills/ (project) or ~/.claude/skills/ (personal, works across all projects)
  • Claude.ai and Desktop - Upload custom skills as a ZIP via Settings, or use pre-built skills from Anthropic (PDF creation, spreadsheets, presentations). Skills sync between web and desktop automatically
  • API - Skills available via endpoints, useful if you’re building your own tools on top of Claude

THE OPEN STANDARD Anthropic published skills as an open standard that other tools have adopted. Microsoft, OpenAI, Cursor, GitHub, Atlassian, and Figma all support the same SKILL.md format. A skill you write for Claude Code can work in other tools too.

Skills you install via /plugin are also published on Anthropic’s skills directory, where companies like Notion, Figma, and Atlassian host official skills. Same name at multiple levels? Personal takes priority over project. Plugin skills use namespacing (plugin-name:skill-name) so they don’t conflict with yours.

SKILLS I ACTUALLY USE

  • /vibe-start - Session start ritual for this blog. Loads my voice guidelines, reads recent posts, checks design tokens, asks what I’m working on
  • /vibe-article - Full content workflow for writing posts on this blog, from topic selection through drafting and scheduling
  • /content-pipeline - Auto-invokes when I mention the backlog or scheduling, checks what’s published, spots gaps, suggests what to write next

The content pipeline is my favorite because I never type /content-pipeline. I just say “what should I write next” and it activates on its own, checks the actual files, and gives me a real answer instead of Claude guessing from memory.

THE BIGGER PICTURE

Last year MCPs were the thing everyone was excited about - connecting Claude to external services and APIs. Skills are getting that same energy right now, and it makes sense when you think about what each one does. MCPs let Claude do things (talk to your database, call an API). Skills let Claude know things - the right way to do them for your exact situation.

A concrete example of why this matters: Anthropic’s built-in /batch skill can take a massive codebase change, like renaming a function across hundreds of files, break it into parallel chunks, run each chunk in its own isolated workspace, and merge the results back. One skill, one command, work that would take you an afternoon.

Your Claude can be different from my Claude, not because the model changed but because we’ve each taught it different workflows. Companies are publishing skills that make Claude an expert in their product. Communities are sharing skills that solve common problems. And you can write your own in a text file without touching code. Simon Willison called skills potentially a bigger deal than MCP, and if you want to understand the technical internals, Mikhail Shilkov wrote a great deep-dive on how they work under the hood.

If you used slash commands before, skills are what they evolved into - same idea, way more capable. This stuff changes fast, so check the official docs if anything here looks outdated.