Claude Code Skills: what they are, when to use them

TL;DR: A Skill is a folder with SKILL.md (YAML frontmatter + Markdown body) plus optional scripts and reference files. Claude reads only the name/description until a task matches, then loads the body [1]. Use a Skill when the workflow has supporting files or you want auto-invocation; a slash command when the prompt is one file and triggered manually; CLAUDE.md for always-on rules; a subagent when you need an isolated context window [5]. Skills are an open standard — Cursor, Copilot, Codex, Gemini CLI, OpenHands and 30+ other agents implement the same SKILL.md format [9].

What a Skill actually is

Anthropic announced Agent Skills on 16 October 2025 [3] and shipped them across Claude.ai, Claude Code, and the API [4]. Mechanically a skill is trivial: a directory containing SKILL.md, optionally extended with scripts, templates, and reference docs [1].

The non-trivial part is progressive disclosure [2]:

1. Discovery — at startup the model sees only name + description (a few dozen tokens per skill) [3].
2. Activation — when the conversation matches the description, the full SKILL.md body is injected.
3. Execution — referenced files and bundled scripts load only if the body says to read them [9].

This is why the official docs describe Skills as the right home for “a section of CLAUDE.md that has grown into a procedure rather than a fact” — CLAUDE.md pays the token cost every turn, a Skill pays it only when relevant [1].

Anatomy of a SKILL.md

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
allowed-tools: Bash(git diff *) Bash(git status *)
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks
you notice such as missing error handling, hardcoded values, or tests that need
updating. If the diff is empty, say there are no uncommitted changes.

This is from the official “first skill” tutorial [1]. Three things make it more powerful than a slash command:

• Dynamic context — !`git diff HEAD` runs before Claude sees the skill; the placeholder is replaced by the command’s stdout, so the model receives the live diff already inlined.
• Pre-approved tools — allowed-tools skips the per-call permission prompt while the skill is active [1].
• Auto-invocation — Claude picks it up when the user just says “what did I change?”, no slash needed.

Nimbalyst’s practical guide — make the trigger an activation condition, not a capability list: “Lead with the use condition. ‘Use this skill when [X].’ The model parses this as a triage rule.” [6].

Frontmatter fields that matter

Only description is technically required. The rest are levers you reach for once a skill is non-trivial [1]:

Skills vs CLAUDE.md vs slash commands vs subagents

The four customization primitives overlap. alexop.dev’s breakdown draws the cleanest lines [5]:

Two practical signals to reach for Skills specifically:

1. You need to bundle scripts or templates — slash commands are single-file; Skills are directories [1].
2. You want Claude to invoke it without being told — Skills are auto-triggered, slash commands are not [5].

As of 2026 the two systems are partially unified: an existing .claude/commands/foo.md still creates /foo, but a Skill at .claude/skills/foo/SKILL.md does the same thing and adds supporting files and auto-invocation. The Skill wins on collision [1].

Where Skills live

Storage location determines scope and precedence [1]:

Enterprise > personal > project on name conflicts. Plugin skills get a plugin-name:skill-name namespace so they cannot collide. Project skills are picked up from every .claude/skills/ between the repo root and the current directory — monorepos can put package-specific skills under packages/frontend/.claude/skills/ and they activate when you edit files there [1].

Bundled skills you get for free

Claude Code ships a set of prompt-based skills in every session [1]:

The /run-skill-generator pattern is worth highlighting: it bootstraps from a clean environment, captures the install + env + launch commands that actually worked, then commits the result as a per-project Skill — converting tribal knowledge into a versioned, agent-readable recipe [1].

The ecosystem in May 2026

The format is now cross-vendor. agentskills.io lists 30+ implementations — Cursor, GitHub Copilot, VS Code, OpenAI Codex, Gemini CLI, OpenHands, Goose, Tabnine, Roo Code, and others all read the same SKILL.md [9]. Anthropic’s own reference repo anthropics/skills ⭐ 140k (May 2026) holds the canonical PDF, DOCX, PPTX, XLSX, creative, and enterprise skills [8].

Community marketplaces have followed:

Simon Willison framed the shift bluntly: “I expect we’ll see a Cambrian explosion in Skills which will make this year’s MCP rush look pedestrian by comparison.” [3]. The star counts above suggest he was right.

⚠ Security: the ToxicSkills problem

The same low friction that makes Skills viral makes them a supply-chain target. Snyk’s ToxicSkills audit of skill registries found [7]:

• 36.82% (1,467 skills) have at least one security flaw
• 13.4% (534) contain a critical-level issue
• 100% of confirmed malicious skills carry malicious code patterns
• 91% of malicious skills also embed prompt injection to bypass the model’s own safety checks

Three attack patterns dominate: external malware downloads, base64/Unicode-obfuscated data exfiltration, and instructions that disable safety mechanisms or plant persistence. The dynamic-context feature (!`cmd`) is the worst offender: commands run before the model ever sees the skill content, so model-level prompt-injection defenses never get a chance to fire [7].

Practical mitigation:

• Review every project Skill before accepting the workspace trust dialog — allowed-tools is granted on trust [1].
• For untrusted sources, set "disableSkillShellExecution": true in settings to neutralize !`cmd` placeholders [1].
• Prefer the source-reference distribution pattern (marketplaces that pin to upstream commits) over copy-paste [12].

When a Skill beats an MCP server

Simon Willison’s argument for why Skills may displace many MCPs: “MCP is a whole protocol specification… skills are Markdown with a tiny bit of YAML metadata and some optional scripts… almost everything I might achieve with an MCP can be handled by a CLI tool instead.” [3]. Anthropic’s own framing is gentler — Skills “complement” MCP by teaching agents how to use the tools MCP exposes [2].

A useful heuristic:

• MCP server when you need a long-lived stateful connection (a database, a SaaS API session, an auth handshake).
• Skill when the operation is a shell command, a Python script, or a procedural recipe — anything where “run this CLI, read the output” is enough.

The Skill is cheaper to build, cheaper to ship, cheaper to audit, and works across every agent that reads SKILL.md — not just the ones with an MCP client [9].