What Are Agent Skills in Claude and How Do You Use Them?

Updated

Agent skills are packaged instructions and resources that extend what a Claude agent can do, and you use them by adding the skill to your agent's workflow so Claude can load and follow it when a task matches. They are best understood as reusable capability modules rather than raw API tools: a skill tells the agent how to perform a class of task, while tools and MCP servers give it access to external systems. The Awesome Claude directory lists agent skills alongside the Claude Code cheatsheet, MCP servers, plugins, SDKs, and integrations, and points to official references for building with them.

How agent skills fit alongside tools, MCP servers, and plugins

These four terms are often used interchangeably, but they play different roles in an agent workflow.

Concept What it provides Typical use
Agent skill Packaged instructions and supporting resources for a task pattern Teaching an agent a repeatable workflow, such as a review or analysis routine
Tool (tool use) A callable function the model can invoke Fetching data, running a calculation, calling an API
MCP server A standardized connector exposing tools and context to Claude Connecting Claude to external systems through the Model Context Protocol
Plugin An extension bundled into a host environment Adding capabilities to Claude Code or an integration

A practical rule: if the agent needs to know a procedure, reach for a skill; if it needs to do something external, reach for a tool or MCP server. Skills and tools compose — a skill can describe when and how to call a tool.

Where to find skills and reference material

The Awesome Claude directory organizes resources into official Anthropic resources, Claude Code and MCP material, community curated lists, and extensions and integrations. For skills specifically, these entries are the most direct starting points:

  • Claude Cookbook — official notebooks and recipes for common patterns including RAG, tool use, Skills, and MCP.
  • Claude Quickstarts — ready-to-deploy example applications.
  • Agent SDKs — claude-agent-sdk-python and claude-agent-sdk-typescript, with documentation at the Agent SDK overview page.
  • Official documentation — full reference for the Messages API, tool use, computer use, prompt caching, structured outputs, citations, MCP Connector, and Claude Code.
  • Community curated lists — additional skill and integration examples maintained outside Anthropic.

Start with the Cookbook's Skills recipes if you want a working pattern to adapt, and use the Agent SDK docs when you need to wire a skill into an actual agent loop.

How skills are packaged and loaded

A skill is a self-contained bundle: instructions plus any supporting files the agent may need. The loading model is progressive — the agent sees a short description of available skills and pulls in the full instructions only when a task calls for them. That keeps context small when many skills are installed.

To add a skill to an agent workflow:

  1. Write the skill — a clear name, a one-line description of when it applies, and step-by-step instructions. Include examples of good output and any reference files.
  2. Register it — make the skill discoverable to your agent, either through the Agent SDK's skill configuration or the host environment's skill directory.
  3. Describe the trigger precisely — the description is what the agent matches against the user's request, so state the task type, not the implementation.
  4. Test with a matching request — confirm the agent loads the skill and follows the steps.
  5. Test with a non-matching request — confirm the skill is not loaded, so it doesn't pollute unrelated tasks.

A minimal example

Suppose you want an agent that reviews pull request descriptions for completeness. The skill bundle contains:

  • Name: pr-description-review
  • Description: "Use when the user asks to review or improve a pull request description."
  • Instructions: check for a summary, motivation, test plan, and linked issue; return a checklist with pass/fail per item and suggested edits.
  • Example: one well-formed PR description and one that fails the checklist.

When a user asks "can you check this PR description?", the agent matches the description, loads the instructions, and produces the checklist. When the user asks "summarize this issue," the skill stays dormant and the agent handles it normally.

Common pitfalls and debugging

  • Skill never triggers. The description is too vague or phrased as an implementation detail. Rewrite it as the user-facing task it covers.
  • Skill triggers too often. The description is too broad. Narrow it to a specific task type and add a negative example.
  • Agent loads the skill but skips steps. Instructions are ambiguous or too long. Break them into numbered steps with explicit expected outputs.
  • Conflicts with tools. If a skill tells the agent to call a tool that isn't available, the workflow stalls. Verify tool availability before relying on it in a skill.
  • Context bloat. Installing many verbose skills degrades performance. Keep each skill focused and lean on progressive loading rather than inlining everything.

To debug, log which skills the agent loads for a given request, then compare that against your intended trigger. If the skill loads but output is wrong, the problem is in the instructions; if it doesn't load, the problem is in the description.

For current model IDs, context windows, and pricing, check the official Models & Pricing page rather than relying on secondhand summaries, since these details change between releases.