Claude Code Skills — The Complete Guide

1. What is a Claude Code skill?

A Claude Code skill is a self-contained module that extends Claude Code with specialized knowledge or capability. In its simplest form, it is a folder with one file:

~/.claude/skills/my-skill/
└── SKILL.md

The SKILL.md file is plain markdown with a YAML frontmatter block at the top. The frontmatter declares when the skill should activate; the body is the prompt content Claude reads when it does.

Skills can also include arbitrary supporting files — Python scripts, shell scripts, templates, config files, reference docs. Those files are referenced from SKILL.md and only loaded when needed (more on this in section 3).

Skills were officially introduced by Anthropic in October 2025 and have rapidly become the dominant way to package reusable capabilities for Claude Code. As of April 2026, the registry tracks 250+ public skills across 15 categories.

2. Anatomy of a SKILL.md file

A minimal SKILL.md looks like this:

---
name: hebrew-seo
description: Optimize Hebrew web content for Google search — title tags, meta descriptions, schema.org, and RTL-aware Open Graph. Use when the user asks for SEO on Hebrew pages or mentions Israeli search ranking.
---

# Hebrew SEO Optimizer

When invoked, follow these steps:
1. Identify the page language and RTL direction
2. Check title length (50-60 chars), meta description (150-160 chars)
3. Validate schema.org markup
4. Verify Open Graph tags use correct hreflang and og:locale
5. Suggest improvements with before/after examples

## Examples

[...]

The two required fields are:

• name — kebab-case identifier, must be unique within the skills directory.
• description — a one-paragraph trigger description. This is the most important field. Claude uses it to decide when to invoke the skill, so describe both what the skill does and what user inputs should activate it.

The body is freeform — typically methodology, examples, references, and step-by-step instructions. Some skills are 50 lines; some are 5,000.

3. Progressive disclosure — the killer feature

Skills do not live in your context window. Until Claude decides one is relevant, only the YAML frontmatter (name + description) is loaded. This is called progressive disclosure and it is the architectural difference between skills and "just include this in CLAUDE.md".

The mechanism works in three layers:

1. Layer 1 — discovery. At session start, Claude scans ~/.claude/skills/*/SKILL.md and reads only the frontmatter. A list of (name, description) pairs is added to context. This is cheap — typically a few hundred tokens for dozens of skills.
2. Layer 2 — invocation. When the user's prompt matches a skill description, Claude reads the body of that SKILL.md and follows its instructions.
3. Layer 3 — supporting files. If SKILL.md references other files (a Python script, a template, a reference doc), Claude loads those on-demand using the Read or Bash tools — only when the skill's logic actually needs them.

This three-layer pattern lets you publish enormous skills (tens of thousands of tokens of methodology) without paying for them on every turn. You only pay for what Claude actually uses.

4. Skills vs MCP, plugins, hooks, slash commands

Claude Code has multiple extension points. They are easy to confuse. Here is the practical decision matrix:

Rule of thumb: if it is knowledge or methodology, write a skill. If it is a stateful tool or external service, write an MCP server. If it is a shortcut the user types, make it a slash command. If it should run automatically on an event, make it a hook.

5. How Claude decides when to invoke a skill

This is the question every skill author obsesses over. The mechanism is simple: Claude reads the description field of every installed skill and matches it semantically against the current user input + relevant tool results.

The practical implications:

• Write descriptions that include trigger phrases. If your skill should activate on the question "is this defamation?", put that exact phrase in the description.
• List both English and Hebrew triggers if you serve both audiences. Description matching is multilingual.
• Be specific about what the skill is not for. Phrases like "do not invoke for theoretical questions about pedagogy without a specific course" reduce false positives.
• Watch for collisions. If two skills' descriptions overlap, Claude may pick either or both. Make your scope distinguishable.

6. Ten skills to install today

Of the 250+ public skills, these are the ten most useful for general-purpose Claude Code workflows in 2026. All are free, MIT-licensed, and verified.

1. superpowers (obra) — TDD, brainstorming, plan-write-execute. The single most-installed skills bundle.
2. skill-creator (anthropics) — meta-skill for authoring new skills. Use this to bootstrap your own.
3. docx (anthropics) — generate professional Word documents.
4. pdf (anthropics) — read, generate, and manipulate PDFs.
5. cc-devops-skills (akin-ozer) — IaC validation, CI/CD generators, K8s/Terraform/Ansible.
6. code-reviewer — opinionated code review with anchor-and-cite output.
7. security-reviewer — pre-merge security pass focused on OWASP top-ten and secrets.
8. n8n-workflow-patterns — production-grade n8n node configurations and patterns.
9. playwright-expert — browser automation with sane defaults and resilient selectors.
10. lahav433 (BDNHOST) — investigative journalism + OSINT + forensic accounting + pre-publication legal review.

To install any of them: open the registry page, copy the install snippet, paste into Claude Code. Done.

7. How to write your own skill

The fastest path is to use the skill-creator meta-skill. After installing it, just say:

I want to build a Claude Code skill that does X.

It will ask the right questions and scaffold the directory structure for you.

If you prefer to write it by hand, here is the minimum viable skill in 30 seconds:

mkdir -p ~/.claude/skills/my-skill
cat > ~/.claude/skills/my-skill/SKILL.md <<'EOF'
---
name: my-skill
description: One paragraph describing what this skill does and when Claude should invoke it. Include trigger phrases the user is likely to use.
---

# My Skill

When invoked, do these things:
1. Step one
2. Step two
3. Step three

## Examples

[Add 1-2 worked examples]
EOF

Restart Claude Code, then verify with: describe what skills you have available.

For production-grade skills, follow these conventions used by the leading authors:

• Keep SKILL.md under 5,000 tokens. Move long reference material to supporting files.
• Pin dependencies. If your skill calls a Python script, list the pinned package versions in a comment.
• Add an example session. The best skills include a worked example showing exactly what good output looks like.
• Version your frontmatter. Add version: 1.0.0 and bump it when behavior changes.
• Test invocation. Before publishing, verify the skill activates on its intended trigger phrases (and only those).

8. Where to discover more skills

The fragmented landscape of "claude-skills" repos and awesome-lists is a discovery problem. We built the Claude Code Skills Registry to solve it.

It auto-discovers new skills daily from GitHub (across 9 trusted source repos plus a code search query) and runs them through a hybrid LLM+keyword classifier into 15 categories. Every skill page has a deep-link URL with rich Open Graph previews and a one-line install snippet.

9. FAQ

What is a Claude Code skill?

A self-contained folder containing SKILL.md plus optional supporting files. The frontmatter declares when Claude should invoke the skill; the body is the prompt content. Skills are loaded on-demand via progressive disclosure.

Skills vs MCP — which should I use?

Use a skill for procedural knowledge, methodology, prompt patterns, code recipes. Use MCP for stateful integrations — databases, APIs, persistent connections, anything that needs to maintain state across calls.

Where can I find Claude Code skills?

claude-skills.bdnhost.net — a curated, auto-discovered catalog of 250+ verified skills aggregated from anthropics/skills, obra/superpowers, jeffallan/claude-skills, akin-ozer/cc-devops-skills, and more.

Are Claude Code skills free?

Yes. Every skill in the registry is free and open-source. Most are MIT or Apache-2.0 licensed.

How do I install a skill?

Clone the source repo, copy the skill folder into ~/.claude/skills/, restart Claude Code. Most registry pages publish a one-line natural-language install prompt you can paste into a Claude Code session.

Can I make skills private to one project?

Yes. Put them in ./.claude/skills/ at the project root instead of ~/.claude/skills/. They will only be visible when Claude Code is invoked from inside that project.

How big can a skill be?

SKILL.md should stay under ~5,000 tokens for fast loading. Beyond that, move content into supporting files referenced from SKILL.md and let Claude load them on-demand.

Can skills run code?

Skills cannot directly execute code, but they can instruct Claude to run included scripts via the Bash tool. The harness's permission model still applies — sandboxed by default, with user approval for sensitive operations.

Further reading

• Anthropic — Claude Code Skills (official docs)
• Anthropic — Introducing Skills (announcement)
• anthropics/skills — official skill set
• obra/superpowers — community-leading bundle
• Claude Code Skills Registry — 250+ skills, auto-discovered
• bdnhost/claude-skills — BDNHOST production skills

Last updated 2026-04-25. Spotted an error or want to add a skill to the registry? Email [email protected] or open an issue at github.com/bdnhost/claude-skills.