Claude Code Skills: The Complete Guide (2026)

If you have used Claude Code for more than a week you have hit the wall: the agent is brilliant at general code, but every time you start a new project it has to relearn your stack — your test runner, your migration tool, your weird CI quirks. You keep pasting the same primer prompt over and over. Skills are the official answer to that grind.

A skill is a small, versioned package of context, instructions, and (sometimes) helper tools that you point Claude Code at once and reuse forever. Think of it as a teammate's onboarding doc that the agent loads on demand instead of dumping into every prompt. This guide covers what skills are, why they matter, how to install and write them, and which skills the community actually uses — pulled from a 2,000-skill index that we update daily at orangebot.ai/skills.

What Are Claude Code Skills?

A Claude Code skill is a directory (usually published as a Git repo or to the skills.sh registry) containing at minimum a SKILL.md manifest and a body of instructions. When invoked, the skill's content is loaded into the agent's working context — but only when relevant — so it can teach the agent a specific capability without permanently inflating the system prompt.

A typical skill looks like this:

my-skill/
├── SKILL.md          # frontmatter + instructions
├── scripts/          # optional helper scripts
└── examples/         # optional reference patterns

The SKILL.md frontmatter declares the skill's name, description, and the triggers (keywords, file types, slash commands) that should activate it. The body is markdown — usually a focused playbook on one capability: "deploy Nuxt to a Caddy reverse proxy", "write a Flutter widget test", "review a SQL migration for unsafe operations".

It's worth contrasting skills against three siblings:

• MCP servers are long-running tool servers (often shipping 10–50 tools each) that the agent can call. They are great for external integrations — GitHub, Linear, a database — but each connected server eats context budget for its tool descriptions, sometimes thousands of tokens before the user has typed anything.
• Sub-agents are delegated tasks. The main agent spawns a child agent with its own context window, lets it work, and gets back a summary. Useful for parallel decomposition (research, large refactors) but not for "teach the agent how X works".
• Slash commands are one-shot prompt templates. Quick to write, but they don't compose, can't bring helper files, and aren't versioned.

Skills sit in the middle: more reusable than a slash command, lighter than an MCP server, and discoverable as proper packages.

Why Skills Matter — The Context Engineering Problem

The Claude Code thesis — and broader Anthropic-team writing under the "context engineering" banner — is that model output quality is a function of context quality, not just model intelligence. Drop a state-of-the-art coder into a project with a bad README and it will produce mediocre code. Give a mid-tier model a precise playbook and it will outperform.

That makes context budget your most precious resource. And the failure mode in 2025–2026 has been tool bloat from MCP: people connect 8 MCP servers, each exposing 20 tools, and the agent's system prompt balloons past 13,000 tokens of tool descriptions before any real work. Throughput drops, cache hit rate craters, and the model starts confusing similar tools.

Skills attack this directly:

1. Opt-in loading. A skill is only read into context when the agent decides it's relevant (via keyword/file-type triggers in the manifest). The other 1,999 skills in your library cost zero tokens until needed.
2. Versioned and shareable. A skill is a Git repo. Pin a version, share with your team, fork to customize. No more "send me your prompt".
3. Narrow scope. Convention pushes skills toward one focused capability per file. "Test this Flask route" is a skill. "Be a senior engineer" is not — that's a persona, and personas are anti-pattern.
4. Composable. The agent can invoke multiple skills in one turn. "Deploy this Nuxt app" might pull a caddy-reverse-proxy skill and a nuxt-build skill together.

The result is that you get the precision of a custom prompt without paying for it on every request.

How to Install a Skill

Skills install per-project (in .claude/skills/) or globally (in ~/.claude/skills/). The fastest way is the official CLI:

# Per-project (recommended for team work)
/skills add owner/repo@skill-name

# Global (good for personal utilities)
/skills add owner/repo@skill-name --global

That command clones the repo into your skills directory, validates the manifest, and registers the trigger keywords. The agent will pick up the skill on the next prompt — no restart needed.

For a real-world example, here's installing one of the most popular community skills, a deep-research orchestrator:

/skills add LichAmnesia/lich-skills@multi-llm-deepresearch

After install you can list what's active with /skills list, disable a specific skill with /skills disable <name>, or check its manifest with /skills show <name>. The skill itself stays on disk so you can read the markdown directly — that's by design. There is no opaque binary; everything is text you can review before running.

The closest analogy is apt install or brew install, but for context rather than software.

The Top 20 Skills by Install Volume

These are the most-installed skills in our 2,000-skill index as of May 2026. Counts are normalized weekly installs across public repos.

A few patterns jump out:

• Devops dominates the top 10: deploy, run, verify, review. These map to the moments where a developer is most likely to ask the agent for help — and where mistakes are most expensive. Skills that codify "how to ship without breaking prod" are immediate wins.
• AI/ML is rising fast. claude-api, nano-banana-pro, and gemini-embedding reflect that many users now build AI features inside their app — they want a skill that knows the SDK quirks of each provider so they don't have to read the docs every time.
• Research and content skills are larger than expected. xray-paper, autoresearch, wiki-index — these are not engineering skills, they are knowledge-work skills. The Claude Code surface is starting to colonize tasks adjacent to coding (reading papers, building wikis) because the same agent is already in the user's IDE.
• Frontend lags backend in install volume. Frontend code is more visual; agents are still weaker at "make this look right". Backend has more deterministic checks (tests, types, lint), so users trust the agent more there. Expect this to flip once visual feedback skills mature.

You can browse the full live list at orangebot.ai/skills — sorted, filterable, and refreshed daily.

Skills by Domain — When to Use What

Skills are most useful when they map cleanly to a workflow you actually do. Here are recommended starter skills by category — pick 2–3 per role, not all of them.

Frontend

• nextjs-app-router — App-Router conventions, server-component vs client-component decisions, metadata API.
• tailwind-audit — flags unused utilities, suggests @apply consolidation, finds responsive-breakpoint gaps.
• shadcn-radix-patterns — accessibility-first component composition patterns.
• Browse more: orangebot.ai/skills/frontend.

Backend

• sqlite-migrations — safe ALTER patterns, rollback strategies, foreign-key checks.
• stripe-webhooks — signature verification, idempotency keys, replay protection.
• rust-clippy — codifies opinionated lints + suggested fixes for common patterns.
• Browse more: orangebot.ai/skills/backend.

Devops

• chrome-devtools-mcp-connect — connect agent to a live Chrome for DOM inspection and console reading.
• ssh-deploy — opinionated remote deploy with health checks and rollback.
• terraform-plan-review — flags risky destroys before apply.
• Browse more: orangebot.ai/skills/devops.

AI/ML

• claude-api — prompt caching, model migration (e.g. Claude 4.6 → 4.7), tool-use patterns.
• gemini-embedding — multi-modal embedding smoke tests and similarity checks.
• nano-banana-pro — text-to-image and image-edit prompts for the Gemini Pro Image model.
• Browse more: orangebot.ai/skills/ai-ml.

Testing

• verify — run the actual app to confirm a change works, not just unit tests.
• playwright-e2e — opinionated Playwright patterns: fixtures, network mocking, parallelization.
• code-review — diff-aware reviewer with adjustable strictness.
• Browse more: orangebot.ai/skills/testing.

The general rule: install skills you would already write a prompt for. If you have a habit of pasting the same context every Monday morning, that's a skill waiting to happen.

How to Write Your Own Skill

The fastest way to learn skills is to write one. Here is a minimal manifest:

---
name: nuxt-deploy-caddy
description: Deploy a Nuxt 4 app to a remote Ubuntu host behind Caddy reverse proxy.
triggers:
  - keywords: ["deploy nuxt", "ship nuxt", "caddy reverse proxy"]
  - files: ["nuxt.config.ts", "Caddyfile"]
---

When the user asks to deploy a Nuxt app:

1. Verify build works locally: `npm run build`.
2. Rsync `.output/` to `<host>:/home/<user>/<app>/.output/`.
3. SSH into host, kill prior PM2 process named `<app>`, start with `pm2 start ecosystem.config.js`.
4. Confirm Caddy reverse-proxy block exists in `/etc/caddy/Caddyfile`.
5. Health-check via `curl -sSf http://<host>:43117/health` — fail loudly if non-200.
6. NEVER use `--force` flags or `rm -rf` on remote.

Five conventions to follow:

1. One focused capability per skill. A skill that "knows everything about Nuxt" will fail. A skill that "deploys Nuxt to Caddy" will succeed.
2. Name in kebab-case, scoped by domain. nuxt-deploy-caddy, not my-deploy-thing.
3. Describe triggers narrowly. If your keywords are too broad, the skill will activate when not wanted and waste context. Prefer 3–5 specific phrases.
4. Write the body in second-person imperative. "Verify the build", "Rsync the output". The agent is a reader, not a peer.
5. Include guardrails. "NEVER do X" lines are read faithfully by the model and prevent the common error modes.

To publish, push the directory to a public Git repo and submit it to the skills.sh registry. The registry indexes the manifest, exposes search, and surfaces install counts — which is how skills like the ones in the top-20 above accumulate signal.

If you write a skill that solves a recurring annoyance in your own workflow, expect strangers to install it. Most popular skills started as personal time-savers.

Skills vs MCP vs Sub-agents

These three patterns get confused a lot. Use this table as a sanity check:

A few rules of thumb:

• If your need is "the agent should know how X works" → write a skill.
• If your need is "the agent should be able to call X (API, database, system tool)" → use an MCP server.
• If your need is "the agent should do five independent things in parallel" → spawn sub-agents.

A common mistake: building an MCP server when a skill would do. If your "tool" is really just "here's how to use ffmpeg correctly", that's a skill — no server needed. MCP servers shine when they handle auth, hold connections, or transform large data; otherwise the context cost dwarfs the benefit.

FAQ

Are skills free? Yes. Skills are markdown files; the registry is free; the install command is built into Claude Code. The only cost is the context tokens consumed when a skill is loaded — which is bounded by the skill's body length and only happens on activation.

Can I use skills with non-Claude agents? Partially. The SKILL.md body is just markdown, so any agent that supports custom system-prompt files can read it. The auto-trigger metadata is Claude-specific, but tools like OpenSeek (the OSS Claude Code alternative) and Codex are adopting similar conventions. Expect a portable spec by the end of 2026.

How do I share a private skill with my team? Push it to a private Git repo, then have each teammate run /skills add <git-url>. The CLI supports private SSH-cloneable repos. For org-wide skills, point your project's .claude/config.json at a shared submodule.

What's the difference between a skill and a slash command? A slash command is a single prompt template, invoked manually. A skill is a multi-file package, can auto-activate via triggers, can bring helper scripts, and is versioned. If you only need a 5-line reusable prompt, use a slash command. If you need state, files, or composability, use a skill.

Do skills slow down the agent? Marginally, only when loaded. A 2,000-skill library with no activations costs zero tokens. A typical activated skill adds 800–2,500 tokens to that turn's context. Compared to a tool-heavy MCP server (which is always in the prompt), skills are dramatically cheaper.

Browse our full 2,000-skill index at orangebot.ai/skills. Updated daily. If you want to dig deeper, two related deep-dives are worth your time: how to write your own Claude skill walks through a complete example, and Claude Skills vs MCP makes the architectural trade-offs concrete with token-budget math.