Agent Skills are organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks. They extend Claude's capabilities by packaging expertise into composable resources, transforming general-purpose agents into specialists. Anthropic
The key distinction that most people miss: Skills teach Claude how to do things better. MCPs give Claude access to new things. This is architectural. One is knowledge, the other is connectivity. Anandbg
When Claude invokes a skill, the system loads a markdown file (SKILL.md), expands it into detailed instructions, injects those instructions as new user messages into the conversation context, modifies the execution context (allowed tools, model selection), and continues the conversation with this enriched environment. This is fundamentally different from traditional tools, which execute and return results. Skills prepare Claude to solve a problem, rather than solving it directly. Lee Hanchung
Without skills, every session with an AI agent starts from zero. You re-explain your stack, your preferences, your brand voice, your review checklist — every single time. A raw Claude without skills is like a senior engineer on day one: brilliant, but missing all the project-specific context that makes them dangerous. Medium
Skills solve this cold-start problem permanently. Unlike prompts (conversation-level instructions for one-off tasks), Skills load on-demand and eliminate the need to repeatedly provide the same guidance across multiple conversations. Claude API Docs
The efficiency gain is real. The design principle behind it is called progressive disclosure.
Like a well-organized manual that starts with a table of contents, then specific chapters, and finally a detailed appendix, skills let Claude load information only as needed. Agents don't need to read the entirety of a skill into their context window when working on a particular task. This means that the amount of context that can be bundled into a skill is effectively unbounded. Anthropic
A project with 50 skills doesn't consume 50x the tokens. Claude scans metadata, identifies the 1-2 relevant skills, and loads only what's necessary. Anandbg
Every skill is a directory. The directory name is the skill name. Inside, there is always a SKILL.md file.
my-skill/
├── SKILL.md ← required: instructions + frontmatter
├── scripts/ ← optional: Python/shell scripts
├── references/ ← optional: extended docs, SOPs
└── assets/ ← optional: templates, fontsSKILL.md is the core of a skill's prompt. It is a markdown file that follows a two-part structure — frontmatter and content. The frontmatter configures HOW the skill runs (permissions, model, metadata), while the markdown content tells Claude WHAT to do. Lee Hanchung
Minimal SKILL.md example:
markdown
---
name: pr-summary
description: Summarize changes in a pull request. Use when user mentions 'PR', 'pull request', or 'code review'.
version: 1.0.0
allowed-tools: Bash(gh *)
---
## Your task
Given the PR diff and comments below, summarize:
1. What changed and why
2. Any risky deletions or regressions
3. Review checklist items to flag
## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`The ! syntax is preprocessing — it runs shell commands before the skill content is sent to Claude. The command output replaces the placeholder, so Claude receives actual data, not the command itself. This is preprocessing, not something Claude executes. Claude only sees the final result. Claude
The description field is the routing rule. Claude reads only this when scanning for relevant skills, so write it like a trigger condition, not a marketing blurb.
SurfacePathScopeClaude Code (personal)~/.claude/skills/Every projectClaude Code (project).claude/skills/That repo onlyClaude Code (plugin).claude-plugin/skills/Shared via pluginclaude.aiSettings → Capabilities → SkillsWeb sessionsAPI/v1/skills endpointWorkspace-wide
Custom Skills are shared workspace-wide; all workspace members can access them when uploaded via the API. Claude API Docs
Claude Code watches skill directories for file changes. Adding, editing, or removing a skill under any watched directory takes effect within the current session without restarting. Claude
Code reviewer skill — The code-reviewer skill runs a structured review pass over any code the agent writes or modifies. It checks for logic that could be simplified or extracted into reusable utilities. Crucially, it doesn't just flag problems — it fixes them. The review loop happens before the code is presented to you. Medium
PR summary skill — Fetches live GitHub data, generates structured summaries, flags regressions. Zero manual prompt setup per PR.
Run skill (via /run-skill-generator) — It gets your app running from a clean environment, captures what worked (the install commands, the env vars, the launch script), and commits it as a per-project skill. After that, /run, /verify, and any other agent in the repo follow the recorded recipe instead of rediscovering it. Claude
The frontend-design skill (277,000+ installs as of March 2026) gives Claude a design system and philosophy before it touches any code. It outputs bold aesthetic choices, distinctive typography, purposeful color palettes, and animations that feel intentional rather than decorative. Without the skill, Claude defaults to a safe, forgettable design. With it, you get components that look like a senior designer reviewed them. Medium
Daily briefings that summarize the last 24 hours of Slack messages, calendar events, and email. Weekly reports that pull data from Google Drive, spreadsheets, and connected tools into a formatted summary. Hatchworks
Workflow automation — skills that run specific processes (analytics audits, SEO reviews, onboarding flows) with a single request. Domain expertise injection — upload your SOPs, style guides, pricing sheets, and competitor analysis; Claude becomes an expert on your business. Badalkhatri
Skills streamline management accounting and finance workflows. Claude processes multiple spreadsheets, catches critical anomalies, and generates reports using established procedures. What once took a day can now be accomplished in an hour. Claude
This comparison is where most developers get confused.
MechanismWhat it isWhen to useSkillReusable domain expertise, loaded on demandRepeated workflows, org SOPs, design systemsMCP ServerTool access to external systemsWhen Claude needs to call something (APIs, databases)Slash CommandNamed prompt shortcutOne-off or rarely varied tasksSystem PromptSession-level instructionWhen every message in a session needs contextCLAUDE.mdGlobal behavioral rulesIdentity-level defaults (never change per project)
Use skills when you're explaining how to use a tool or follow procedures: "When querying our database, always filter by date range first," "Format Excel reports with these specific formulas," "Follow our code review checklist before approving PRs." Use MCP when Claude needs to access something external. Anandbg
Skills are SKILL.md files that provide specialized instructions to the agent. Sub-agents are separate Claude instances that the main agent invokes for specific tasks with isolated context. Agent Teams are multiple agents working in parallel, coordinated by an orchestrator. All three levels can be combined in a single system. Duotach
The real power: combine MCP + Skills together. MCP handles connectivity. Skills handle the knowledge of what to do once connected.
Imagine Claude is a really smart new kid who just joined your class. They're brilliant — can solve any math problem, write great essays, help with science projects. But on Day 1, they don't know anything specific about your school. They don't know your teacher's rules, your class's style, or how your group does things.
Skills are like a cheat sheet you give the new kid before they start helping.
You write down: "In our class, we always show our working. We never use bullet points in essays. When Ms. Johnson says 'quick check,' she means look at your rubric first." Now the new kid instantly knows your rules — and they remember them every time, without you repeating yourself.
The cool part is the new kid doesn't read the whole cheat sheet every second. They glance at the title ("Math rules"), and only open to the math section when you're doing math. Reading rules when writing an essay would just be confusing and slow.
You can have one cheat sheet just for yourself (your personal skills), one for your whole team (project skills), or one that the whole school uses (workspace skills).
And anyone can write a cheat sheet. You don't have to be a teacher. If you figure out the best way to do something, you write it down and share it — and now the whole class benefits forever.
That's all a skill is: a saved explanation of how to do something well, that Claude reads automatically when it's relevant, so you never have to explain it again.
Skills are the most underutilized and most impactful feature in the entire Claude ecosystem right now. Most developers are still treating AI agents like chatbots — asking the same thing repeatedly, pasting the same context, re-explaining the same preferences. Skills eliminate that entirely.
The architectural decision to use progressive disclosure is genuinely smart. It means you can load dozens of skills into a project without bloating every prompt. Claude scans metadata, picks the relevant one, loads the detail only when needed. That scales.
The open standard published in December 2025 is the move that makes this durable. The same skill files work whether you're using Claude or other AI platforms. Anthropic has been collaborating with ecosystem members on the standard. That means skills you build today work across Cursor, Gemini CLI, Codex CLI, and whatever comes next. Write once, reuse everywhere. Anthropic
The one honest criticism: the description-as-routing-rule pattern is fragile at scale. With 20+ skills in a project, you can get collision — two skills match the same task. Anthropic hasn't shipped a resolution mechanism for this yet beyond "write better descriptions." It's workable, but it's a gap.
For teams: start with a brand-voice skill, a code-reviewer skill, and one skill for your most painful repeated workflow. That alone will save hours per week and immediately demonstrate the value to the rest of the org.