Claude Agent Skills: The Complete Guide for 2026

Agent Skills are the feature that turns Claude from a smart generalist into a reliable specialist. Instead of pasting the same instructions into every conversation, you package a workflow once — and Claude picks it up automatically whenever it's relevant. This guide covers what skills are, how the clever "progressive disclosure" architecture works, how to build one, where to find thousands more, and the security you can't skip.

What are Claude Agent Skills?

A skill is a folder that packages instructions, metadata, and optional resources (scripts, templates, reference docs) that Claude uses automatically when relevant. Think of it as an onboarding guide you'd write for a new teammate: here's the task, here's the workflow, here are the tools. Unlike a prompt — which is a one-off instruction for a single conversation — a skill is created once and reused across every conversation, loading only when needed.

The payoff is three things: you specialize Claude for a domain, you stop repeating the same guidance, and you can compose skills to build complex workflows. Anthropic ships pre-built skills for PowerPoint, Excel, Word, and PDF, and you can author your own for anything from your company's code style to a data-cleaning pipeline.

How they work: progressive disclosure

This is the clever part. Skills live as directories on Claude's virtual machine, and Claude reads them with bash exactly like you'd navigate files on your own computer. That filesystem model enables progressive disclosure — loading information in stages so your context window only ever holds what the current task needs.

The consequence is powerful: you can install dozens of skills with almost no context penalty, because Claude only holds each skill's one-line description until the moment it's needed. Bundled scripts are even better — when Claude runs validate_form.py, the code never enters context, only its output does. There's no practical limit on how much reference material a skill can bundle.

How to build a SKILL.md

Every skill needs one required file: SKILL.md, with YAML frontmatter and instructions. Here's the minimal shape:

---
name: pdf-processing
description: Extract text and tables from PDFs, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or extraction.
---

# PDF Processing

## Instructions
Use pdfplumber to extract text. For form filling, see FORMS.md.

## Examples
[Concrete examples of using this skill]

The rules that matter: name is lowercase letters, numbers, and hyphens (max 64 chars, and it can't contain "anthropic" or "claude"), and description (max 1024 chars) must say both what the skill does and when Claude should use it — that description is the only thing Claude sees until the skill triggers, so make it count. A fuller skill adds optional files:

pdf-skill/
├── SKILL.md      # required — instructions + frontmatter
├── FORMS.md      # optional — extra guidance loaded on demand
├── REFERENCE.md  # optional — detailed reference
└── scripts/
    └── fill_form.py   # optional — code Claude runs via bash

Where skills work

Note: custom skills don't sync across surfaces — a skill uploaded to claude.ai isn't automatically available via the API or in Claude Code, and vice versa.

Where to find skills

Beyond Anthropic's pre-built skills and its open-source skills repository, a whole marketplace ecosystem sprang up in 2026:

• ClaudeSkills.info — the largest marketplace, with 30,000+ free, open-source Claude Code and agent skills.
• SkillsMP — a searchable directory that indexes public GitHub repos so you can inspect the source before installing.
• LobeHub — a cross-assistant directory covering Claude, Codex, and ChatGPT skills.
• The official Anthropic directory baked into Claude Code — small, but every skill is reviewed and trusted.

Best practices

• Nail the description. It's the only thing Claude sees until the skill triggers — state clearly what it does and when to use it, with the trigger words a user would say.
• Keep SKILL.md lean. Aim for under 5k tokens; push detailed references into separate files that load on demand.
• Use scripts for determinism. When an operation should be reliable and repeatable, ship a script rather than asking Claude to regenerate the code each time.
• Add resources only when they earn their place. Start minimal; bundle templates and examples only when they make the skill genuinely more useful.
• Compose, don't cram. Several focused skills beat one giant one — Claude picks the right specialist per task.

Security: read before you install

A skill can run code and invoke tools. A malicious one can exfiltrate data or misuse permissions — treat installing a skill like installing software.

This isn't hypothetical. Snyk's "ToxicSkills" research found prompt injection in 36% of the community skills it tested, and community marketplaces index public repos without certifying that every skill is safe. Before you add any skill from an untrusted source:

• Audit every file — SKILL.md, scripts, and any bundled resources. Look for unexpected network calls or file access that doesn't match the stated purpose.
• Be wary of external fetches. Skills that pull content from URLs are higher risk — that content can carry injected instructions.
• Prefer trusted sources — skills you wrote, Anthropic's official ones, or code you've fully reviewed — especially in production with access to sensitive data.