What Are Claude Skills? How to Create, Use, and Share Them

I have 22 active skills installed in Claude Code right now. They cover SEO methodology, Snowflake SQL patterns, API schemas, financial calculations, document processing, and design tokens. When I ask Claude Code to do keyword research, it automatically loads the DataForSEO patterns, prioritization frameworks, and content strategy principles I encoded months ago. No re-prompting. No context wasted.

That is what skills do. And most people using Claude Code do not know they exist. The ones who do often build them wrong. A bad description means Claude never activates the skill. You end up with a perfectly written SKILL.md file sitting in the right directory, doing absolutely nothing. I know because that happened to me with my first three skills before I figured out why.

What Are Claude Skills?

Claude Skills are folders containing a SKILL.md file that Claude dynamically loads when relevant to your task. Each skill teaches Claude procedural knowledge in a specific domain. They are expertise packages, not plugins.

Anthropic launched Skills on October 16, 2025.¹ By December 2025, the concept was published as an open standard at agentskills.io.² By March 2026, the ecosystem had grown to 283,000+ skills indexed on SkillsMP, 8,097 stars on the awesome-claude-skills repo, and adoption from Microsoft, OpenAI, and Cursor.²

Here is the definition that matters for how you build with them. Skills teach Claude what to do. MCP servers give Claude tool access. Subagents give Claude isolated execution. Skills are knowledge. MCP is connectivity. Subagents are delegation. Most people confuse the first two. That confusion costs them the most powerful extensibility feature Claude Code offers.

The design breakthrough is context cost. A skill costs roughly 30 to 50 tokens at scan time, based on Simon Willison's analysis.³ Full instructions load only when activated, staying under 5,000 tokens. Until Claude decides a skill is relevant, you pay nothing. Zero context pollution. This is what makes 22 skills practical where 22 MCP connections would bury your context window.

How Does the Loading System Work?

Skills follow a three-level activation model. Understanding it is the difference between skills that fire reliably and skills Claude ignores completely.

Level 1. Metadata scan (roughly 30 to 50 tokens). Claude reads the name and description of every installed skill at session start. That is the entire cost. For 22 skills, I pay roughly 700 tokens of overhead. Negligible.

Level 2. Relevance check. When you give Claude a task, it evaluates whether any skill applies. This is where most people get burned. Claude is conservative. It "under-triggers" skills, meaning it will not consult a skill for tasks it believes it can handle independently. Your description field determines whether this check passes or fails.

Level 3. Full load (under 5,000 tokens). If Claude decides a skill is relevant, it loads the complete instructions, scripts, and resource references into context. Now Claude has domain expertise for your specific workflow. The full payload stays available for the remainder of the task. When my SEO keyword research skill loads, Claude suddenly knows my exact prioritization rubric, scoring methodology, and output format preferences. Without the skill, it guesses. With it, it executes.

This part actually matters. Simon Willison called skills "maybe a bigger deal than MCP."³ The reason is the activation model. MCP servers load upfront and stay loaded. Skills load only when needed. That architectural choice is what makes the system scale.

Why Does the Description Field Determine Everything?

I learned this the hard way. I built my first three skills with generic descriptions like "helps with SEO tasks" and "useful for data queries." Claude almost never activated them. The skills existed. They were installed correctly. They were invisible because the descriptions did not signal activation clearly enough.

Let me be specific. The description field in SKILL.md has a 200-character limit. Those 200 characters are the only thing Claude reads during the metadata scan. If your description does not precisely communicate when the skill should activate, Claude will skip it every time. It is not a marketing blurb. It is a trigger condition.

A bad description: "Helps with Snowflake queries and data tasks."

A good description: "Use for Snowflake SQL, data warehousing, role permissions, warehouse configs, query optimization, and cloud data engineering."

The second version lists specific trigger words Claude can match against incoming tasks. The difference in activation rate is not subtle. After rewriting all 22 of my descriptions with this pattern, skill activation went from inconsistent to reliable.

Here is the real issue. Most skill guides treat the description as metadata. It is not metadata. It is the most important field in the entire file. Get it wrong and Claude will never use your skill. Get it right and Claude becomes a domain expert in your workflow automatically.

How Do You Create a Skill?

The file structure is simple.

~/.claude/skills/my-skill/
  SKILL.md        # Required
  scripts/        # Optional
  resources/      # Optional

SKILL.md is the only required file. It has two parts. YAML frontmatter and an instructions body.

The frontmatter specifies the name (max 64 characters, lowercase-hyphenated) and the description (max 200 characters). The instructions body tells Claude what to do when the skill activates. Keep it focused. One skill should equal one capability.

Here is a real example, generalized from one of my SEO skills:

---
name: seo-keyword-research
description: "SEO keyword research methodology. Use for finding keywords, keyword strategy, seed keywords, competitor keywords, keyword prioritization, Business Potential scoring, Traffic Potential analysis, and keyword difficulty assessment."
---

# SEO Keyword Research

When the user asks for keyword research, follow this methodology:

1. Start with seed keyword expansion using DataForSEO
2. Analyze search volume, keyword difficulty, and CPC
3. Score each keyword on Business Potential (1-3 scale)
4. Calculate Traffic Potential using parent topic analysis
5. Prioritize by: Business Potential > Traffic Potential > KD
6. Output as CSV with columns: keyword, volume, KD, BP, TP, intent

One skill. One capability. One clear trigger condition. That is the pattern.

Where to Store Skills

Three locations, each with different scope.

Personal (~/.claude/skills/). Available in every project on your machine. This is where I keep all 22. SEO methodology, Snowflake patterns, API schemas. They travel with me regardless of which project I open.

Project (.claude/skills/). Lives in the project directory, shared via git with your team. Good for project-specific domain knowledge that every team member needs.

Organization (managed via admin controls). Available on Claude Team and Enterprise plans for company-wide skill distribution. This is where skills start to look like a knowledge management system, not just a personal productivity tool. A company could encode its entire engineering playbook, compliance requirements, or style guidelines as skills that every team member inherits automatically.

How Do You Build Skills at Scale?

I did not write them all by hand. I built a tool.

The skill creator is a Python pipeline that scrapes documentation websites and converts them into skills automatically. The workflow:

1. Scrape docs site (universal scraper with 8 framework presets)
2. Categorize content by topic and code language
3. Enhance with Claude to turn raw docs into structured instructions
4. Package as SKILL.md with proper YAML frontmatter
5. Install to ~/.claude/skills/

That pipeline is how I built all 22 of my active skills. Each one represents a domain I work in repeatedly. The SEO cluster alone (4 skills) was built from over 100 source articles following semantic SEO methodology. When I start a keyword research session now, Claude already knows the prioritization framework, the Business Potential scoring rubric, and the exact DataForSEO API patterns to call. No setup. No re-prompting. Just work.

The project management API skill was scraped directly from the platform's developer docs. I used to re-read those docs at the start of almost every session. Now Claude knows the exact endpoints, authentication patterns, and field schemas for task CRUD, doc management, and workspace queries. That one skill probably saves 15 minutes per day.

Here is the full breakdown by category:

Category	Count	What They Cover
SEO	4	Keyword research, topical maps, content creation, content strategy
APIs	4	Project management, Google Sheets, RapidAPI, accounting
Data	1	Snowflake SQL patterns, role permissions, warehouse configs
Automation	2	n8n workflows, Apify web scraping
Finance	2	Canadian financial advising, quant stock research
Design	2	Canvas design, theme factory brand tokens
Productivity	2	File organization, document processing (DOCX, PDF, PPTX)
Dev Platforms	2	Google ADK, YouTube transcript extraction
Learning	1	Ship-Learn-Next framework for progressive deliverables
Domain	2	UFC statistics, Canadian financial context

22 skills means Claude Code starts every session knowing my SEO methodology, my SQL patterns, my API schemas, and my financial calculations. The alternative is re-explaining all of this every single time. Skills are compounding interest for AI productivity.

How Do Skills Compare to MCP Servers and Subagents?

This question comes up constantly and the answer is simpler than people think. Let me ground it in how I actually use all three daily.

My Snowflake MCP server gives Claude data access. It can query tables, list schemas, describe columns. That is a tool.

My Snowflake skill teaches Claude our SQL patterns, role permissions, warehouse configurations, and query optimization rules. That is knowledge.

My revenue query subagent uses both. The MCP provides the database connection. The skill provides the domain expertise. The subagent runs the analysis in an isolated context window. That is delegation.

Dimension	Skills	MCP Servers	Subagents
What it provides	Procedural knowledge	Tool and data access	Isolated task execution
Context cost	~30-50 tokens until activated	Loaded upfront per session	Separate context window
Activation	Automatic (Claude decides)	Always available	Explicitly delegated
Best analogy	Recipe book	Toolbox	Specialist coworker
Use when	Claude needs domain expertise	Claude needs external data or tools	Task needs isolated execution

People use the phrase "AI extensibility" as if skills, MCP, and subagents are interchangeable. They are not. Skills extend knowledge. MCP extends capability. Subagents extend capacity. Mixing them up leads to building MCP servers when you need a SKILL.md, or writing 500-line prompts when you need a subagent. If you are evaluating how Claude Code's extensibility compares to Cursor's approach, this three-layer model is the key differentiator.

What Does the Skills Ecosystem Look Like?

The ecosystem grew faster than most people expected.

Official skills. Anthropic maintains 12+ skills covering document processing (DOCX, PDF, PPTX, XLSX), canvas design, webapp testing, brand guidelines, and a skill creator template.

Community. The awesome-claude-skills repository hit 8,097 GitHub stars and 623 forks. It is the central directory for community-contributed skills.

Marketplaces. SkillsMP has indexed over 283,000 skills. skills.pub hosts 400+. claude-plugins.dev indexes 23,000+.

Open standard. The Agent Skills specification was published December 2025 and adopted by Microsoft (VS Code, Copilot), OpenAI (Codex CLI), and Cursor.² Skills are not locked to Claude. They are becoming the standard format for teaching any AI agent domain expertise.

Built-in Claude Code commands. Commands like /debug, /batch, and /simplify are themselves skills that ship with Claude Code. They follow the same SKILL.md architecture under the hood. If you have used any of these commands, you have already used a skill without realizing it.

Skills represent something larger than a feature release. They are part of the shift from generative to agentic AI. The moment AI stopped being a tool you prompted and became a system you configured.

What Are the Best Practices for Building Skills?

After building 22 skills and watching several of them fail before I fixed them, here is what I know works.

Write the description first. Before you write a single instruction, write the 200-character description. It determines whether Claude ever uses the skill. If you cannot articulate when the skill should activate in 200 characters, your skill is probably trying to do too much.

One skill per capability. Do not create mega-skills that cover an entire domain. My SEO workflow is four separate skills (keyword research, topical maps, content creation, content strategy), not one monolithic "SEO" skill. Smaller scope means more precise activation.

Test activation explicitly. After installing a skill, ask Claude tasks that should trigger it and tasks that should not. If it fires on the wrong tasks or does not fire on the right ones, rewrite the description. This testing loop is non-negotiable.

Keep instructions under 5,000 tokens. The full load budget is approximately 5,000 tokens. Go over and you are eating context that should be available for the actual work. Be precise, not exhaustive.

Use the official skill-creator template. Anthropic provides a skill creator that scaffolds the correct structure. Start there, not from a blank file. If you are building skills at scale, consider building a creation pipeline like I did. Manually writing 22 SKILL.md files would have taken weeks. Automating the scrape-categorize-enhance-package workflow turned it into a weekend project that keeps paying dividends.

The bottom line is simple. Skills are text files with a good description. The description controls activation. The instructions control behavior. Everything else is optimization.

Skills also work in Cowork for knowledge work beyond coding. The same SKILL.md format applies whether you are building software, running research workflows, or analyzing financial data.

If you want help building a skills architecture for your team or project, that is what my AI consulting practice does.

---

Sources

1. Anthropic, "Extend Claude with Skills" (October 2025)
2. Agent Skills, "Open Standard Specification" (December 2025)
3. Simon Willison, "Claude Skills are awesome, maybe a bigger deal than MCP"
4. GitHub, "awesome-claude-skills"
5. SkillsMP, "Skills Marketplace"