Agent Skills Explained: What They Are and How They Work

An Agent Skill is a folder that teaches an AI agent how to do a specific job. At minimum it holds one file, SKILL.md, with a short name and description at the top and plain Markdown instructions below. It can also bundle scripts, reference documents and templates. The agent reads only the name and description up front, and pulls in the rest when a task actually needs it. For a shorter overview, see what are agent skills.

Anthropic introduced Agent Skills for Claude in October 2025 and published the format as an open standard in December 2025. The spec now lives at agentskills.io, and tools beyond Claude read the same files, including OpenAI Codex, GitHub Copilot in VS Code and Gemini CLI. This guide covers what skills are, how they load, where they run, what can go wrong security-wise, and how to find and install good ones.

What an Agent Skill actually is

Think of a skill as an onboarding packet for an agent. A new teammate does not need your whole wiki on day one. They need to know which documents exist and when to open them. Skills work the same way.

The Agent Skills specification defines a skill as a directory with a required SKILL.md and optional folders:

pdf-processing/
├── SKILL.md          # required: metadata + instructions
├── scripts/          # optional: code the agent can run
├── references/       # optional: extra docs loaded on demand
└── assets/           # optional: templates, schemas, images

A minimal SKILL.md looks like this:

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

# PDF processing

## Extract text
Use pdfplumber. Read one page at a time for large files.

## Fill forms
See [references/FORMS.md](references/FORMS.md) for the full workflow.

Only two fields are required: name and description. The name is lowercase letters, numbers and hyphens, up to 64 characters. The description can be up to 1,024 characters and should say both what the skill does and when to use it. The full list of optional fields, folder conventions and limits is in our breakdown of the SKILL.md format.

Skills are not a new model feature or a fine-tune. They are files. That makes them easy to version in Git, review in a pull request and share between people and tools.

How progressive disclosure works

The core idea behind skills is progressive disclosure. Anthropic's engineering post calls it the design principle that makes skills scale. Content loads in three levels, as described in the Claude docs:

Level	When it loads	Rough cost	What it contains
1. Metadata	Always, at startup	About 100 tokens per skill	name and description
2. Instructions	When the skill is triggered	Under 5,000 tokens recommended	The SKILL.md body
3. Resources	Only when needed	Nothing until accessed	Reference files, scripts, assets

Here is what that looks like in practice:

1. At startup, the agent adds each installed skill's name and description to its system prompt.
2. You ask, "Pull the totals table out of this invoice PDF."
3. The agent matches your request against the descriptions and decides pdf-processing is relevant.
4. It reads SKILL.md into context.
5. The instructions mention a forms guide, but your task is extraction, so it never opens that file.
6. If the instructions say to run a script, the agent runs it and only the script's output enters context. The script's source code does not.

Two consequences matter for anyone using skills. First, you can install many skills without filling up the context window, because each one costs only its metadata until used. Second, the description is everything. If it is vague, the agent will not pick the skill. If it is too broad, the agent will pick it for the wrong tasks.

The spec recommends keeping SKILL.md under 500 lines and moving detail into separate files that are linked one level deep. Anthropic's authoring best practices give the same advice.

What skills are good for

Skills shine when an agent already has general ability but lacks your specific context or procedure. Common examples:

• Document work. Anthropic's own pre-built skills create and edit Word, Excel, PowerPoint and PDF files.
• House style. Brand guidelines, report templates, commit message formats or a code review checklist.
• Repeatable workflows. "Cut a release," "triage a support ticket," "run our data quality checks," with a script doing the fragile parts.
• Domain knowledge. Table schemas for your data warehouse, internal API conventions, compliance rules.

A useful rule from Anthropic's guidance: only write down what the model does not already know. A skill that explains what a PDF is wastes tokens. A skill that says "always exclude test accounts from revenue queries" saves you from a real mistake.

Skills do not connect to live systems; that is what an MCP server does. Skills and MCP servers often work best together, a topic we cover in Agent Skills vs MCP servers.

Where Agent Skills run

Skills started in Claude's products, but the format is now portable. Paths and behaviour differ by tool, so check each one's docs.

Claude apps (claude.ai)

According to the Claude docs, claude.ai includes pre-built skills for documents that work with no setup. You can upload custom skills as zip files under Settings, then Features. This is available on Pro, Max, Ultra, Team and Enterprise plans with code execution turned on. Custom skills on claude.ai are per user. They are not shared across an organization automatically.

Claude Code

Claude Code reads skills straight from the filesystem. No upload needed:

• Personal skills: ~/.claude/skills/<skill-name>/SKILL.md, available in all your projects.
• Project skills: .claude/skills/<skill-name>/SKILL.md, committed to the repo and shared with your team.
• Plugin skills: bundled inside a Claude Code plugin and namespaced by plugin name.

In Claude Code, skills also act as slash commands. A skill named deploy can be run as /deploy, and Claude can load it on its own when relevant. Extra frontmatter fields let you turn either behaviour off. Claude Code watches skill folders, so edits take effect in the current session without a restart.

The Claude API and Agent SDK

On the Claude API, skills run inside the code execution tool's container. You reference pre-built skills by ID (pptx, xlsx, docx, pdf) or upload your own through the /v1/skills endpoints. The guide allows up to 20 skills per request and an upload under 30 MB uncompressed. Custom skills uploaded through the API are shared across the workspace. Anthropic's engineering post also lists the Claude Agent SDK as a supported surface.

One catch: custom skills do not sync between surfaces. A skill uploaded to claude.ai is not available in the API, and Claude Code skills live only on disk.

Other agents that adopted the format

Because the format is an open standard, the same folder can work in several tools:

• OpenAI Codex scans .agents/skills in your repo and ~/.agents/skills for your user, and lets you mention a skill with $ or browse with /skills (Codex docs).
• GitHub Copilot in VS Code reads .github/skills/, .claude/skills/ and .agents/skills/ in a project, plus personal folders such as ~/.copilot/skills/ (VS Code docs).
• Gemini CLI reads .gemini/skills/ or .agents/skills/, and asks for your consent before it activates a skill (Gemini CLI docs).
• Cursor reads .agents/skills/ and .cursor/skills/ in a project, ~/.agents/skills/ and ~/.cursor/skills/ for your user, and also the Claude and Codex folders for compatibility (Cursor docs).

Which agents support skills, and where do the folders go?

Agent	Project folder	User folder	Source
Claude Code	.claude/skills/	~/.claude/skills/	Claude Code docs
OpenAI Codex	.agents/skills/	~/.agents/skills/	Codex docs
GitHub Copilot in VS Code	.github/skills/, .claude/skills/, .agents/skills/	~/.copilot/skills/	VS Code docs
Gemini CLI	.gemini/skills/, .agents/skills/	See docs	Gemini CLI docs
Cursor	.agents/skills/, .cursor/skills/	~/.agents/skills/, ~/.cursor/skills/	Cursor docs
claude.ai	Upload a zip under Settings, then Features	Per user	Claude docs

.agents/skills/ is the one project folder that Codex, VS Code, Gemini CLI and Cursor all read.

The client showcase on agentskills.io lists more. Required fields are the same everywhere, but optional fields vary. Codex, for example, keeps extra UI and policy metadata in an agents/openai.yaml file. Tools generally ignore fields they do not understand, so a skill written to the core spec is the most portable.

Runtime differences that affect skills

Where a skill runs changes what its scripts can do. The Claude docs spell it out:

• Claude API: no network access and no installing packages at runtime.
• claude.ai: network access ranges from full to none, depending on user and admin settings.
• Claude Code: full network access, the same as any program on your machine.

That last point is the one to remember. A skill running in a local coding agent has roughly the same reach as a script you run yourself.

Are agent skills safe? What the research says

A skill looks like documentation, which makes it easy to underestimate. But it can contain scripts the agent will execute, and its instructions can tell the agent to call tools, read files or fetch URLs. Anthropic's docs are direct about this: use skills only from trusted sources, and treat installing one like installing software.

The specific risks Anthropic calls out:

• Bundled code. A script in scripts/ can do anything your shell can do. In Claude Code that includes reading your files and making network requests.
• Instructions that misuse tools. A malicious SKILL.md can direct the agent to run commands or move data in ways unrelated to the skill's stated purpose.
• External content. Skills that fetch from URLs can pull in text that contains hidden instructions, a form of prompt injection. See our guide to prompt injection in tool-using agents.
• Drift. A skill that was safe when you installed it can change later if it pulls from a remote source or you update it without reading the diff.

These are the same patterns that show up in wider AI agent supply chain attacks.

Research backs up the caution. A survey by Renjun Xu and Yang Yan, Agent Skills for Large Language Models (arXiv, last revised June 2026), reports that recent empirical analyses found 26.1% of community-contributed skills contain vulnerabilities. In response it proposes a Skill Trust and Lifecycle Governance Framework: a four-tier, gate-based permission model that grants a skill more deployment capability depending on where it came from.

What do signed and verified skills prove?

Some publishers now ship extra evidence with a skill. NVIDIA's agent skills glossary describes three pieces:

Piece	What it is	What it shows	What it does not show
Detached signature	A signature file shipped next to the skill	Who published it, and that the files have not changed since signing	That the publisher's code or instructions are harmless
Security scan	A check run before publication	That the scanner's rules did not flag the skill when it ran	Anything the rules do not cover, such as harmful plain-English instructions
Skill card	A machine-readable document with owner, purpose, tools and APIs accessed, limitations, licence and scan or evaluation status	What the publisher declares	That the declaration is complete or accurate

A signature answers "is this the file the publisher released?", not "should I run it?". You still need to read what the skill does.

How to audit a skill before installing

A short checklist you can run in a few minutes:

1. Read SKILL.md in full. Does every step match the description? Watch for instructions to send data anywhere, disable checks or "ignore previous instructions."
2. Open every script. Look for eval, shell execution with built strings, base64 blobs, reads of environment variables that hold secrets, and network calls.
3. Check references and assets. Hidden instructions can sit in a reference file or even an image.
4. Look for URLs and IPs. Any outbound domain should have an obvious reason to be there.
5. Check dependencies. If a script installs packages, check those packages too.
6. Limit what the agent can do. Run it with the least access needed. Our post on least privilege for AI agents covers this in depth.

For a broader version of this list, see our is this AI agent safe checklist.

Where automated scanning helps

Manual review does not scale when you are comparing dozens of community skills. On AgenticMart, any listing can get a free automated scan; each listing page shows its scan status. A scan runs on a fresh GitHub Actions virtual machine that is destroyed afterwards. It runs static analysis with Semgrep plus custom rules for eval, shell execution, hidden environment variable reads and obfuscation. It checks for leaked secrets with Gitleaks and for known-vulnerable dependencies with OSV-Scanner. It then installs and starts the code in a locked-down Docker container and records outbound network traffic, flagging undeclared domains and hard-coded IPs. The full report is public, and the results feed into badges and a 0 to 100 trust score. How verification works has the details.

A scan cannot prove a skill is 100% safe. Instructions in plain English can be harmful without any suspicious code, and behaviour can depend on the task. Use scan results to narrow down what to read closely, not as a replacement for reading.

Where to find and install agent skills

Where to find skills

• Registries and catalogs. NVIDIA's agent skills glossary names NVIDIA/skills on GitHub, skills.sh, ClawHub and Hugging Face as places to discover, install and version skills. Being listed in a registry does not mean a skill was reviewed.
• Anthropic's skills repository has example skills plus the source for the document skills. Many are Apache 2.0. The document skills are source-available rather than open source.
• Vendor docs and built-ins. Claude, Codex and Gemini CLI each ship some skills.
• Community repos on GitHub. The largest pool, and the one that needs the most care.
• Marketplaces. You can browse the agent skills directory on AgenticMart, where each listing page shows its scan status and links to the report when there is one. The marketplace detects a skill repo by a SKILL.md file or a skills/ folder.

Installing a skill

The steps depend on the tool.

Claude Code, from Anthropic's repo as a plugin:

/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills

Claude Code, any skill folder: copy the folder into your personal or project skills directory. The folder name should match the skill's name.

git clone https://github.com/example-org/example-skills.git
cp -r example-skills/skills/release-notes ~/.claude/skills/

claude.ai: zip the skill folder and upload it under Settings, then Features.

Codex, VS Code or Gemini CLI: place the folder in .agents/skills/ in your repo, which all three read, or in the tool's own folder.

Claude API: upload the folder through the Skills API, then list its skill_id in the container parameter alongside the code execution tool.

After installing, check the agent can see it. In Claude Code, run /skills. Then try a prompt that should trigger it and one that should not.

Writing your own skill

If you keep pasting the same context into chats, that is a skill waiting to be written. Anthropic recommends starting from real failures: run the agent without a skill, note where it goes wrong, and write only enough to fix those gaps. The skills-ref tool from the spec project validates frontmatter and naming:

skills-ref validate ./my-skill

Our step-by-step tutorial on how to write an Agent Skill builds a release notes skill with a bundled script, tests whether it triggers, and publishes it to GitHub. If you plan to share it, you can submit the repo for a free scan so users can see the report before they install.

FAQ

Are Agent Skills only for Claude?

No. Anthropic created the format and released it as an open standard at agentskills.io. Tools including OpenAI Codex, GitHub Copilot in VS Code and Gemini CLI read SKILL.md folders, though each has its own install paths and optional extras.

Do skills use up my context window?

Barely, until they are used. Each installed skill costs roughly 100 tokens for its name and description. The full instructions load only when the skill is triggered, and scripts add only their output.

Are Agent Skills safe to install?

They are as safe as the code and instructions inside them. Skills can run scripts and steer the agent's tool use, so treat them like any software you install: use trusted sources, read the files, and check any automated scan report before you rely on it.

What is the difference between a skill, a tool and a model?

The model is the part that reasons. A tool is a single callable function, such as a web search or a file read. A skill is a set of instructions, and optionally scripts, that tells the model which tools to use and in what order for a job. NVIDIA's glossary puts it as the model being the engine, tools the levers, and skills the playbook.

Do skills work across platforms?

Mostly. A skill written to the core Agent Skills specification, with only name, description and Markdown instructions, is read by Claude Code, Codex, VS Code, Gemini CLI and Cursor. Install folders differ by tool (see the table above), optional fields vary, and scripts only work if the runtime allows them, for example the Claude API has no network access.

What is the difference between a skill and a prompt?

A prompt applies to one conversation and you have to repeat it. A skill sits on disk, loads automatically when a task matches its description, and can bundle scripts and reference files that a prompt cannot.