Anthropic agent skills
AI Agents

Anthropic Agent Skills: What They Are and How They Work

By Harry | Published: November 18, 2026

Anthropic agent skills are folders of instructions, scripts, and reference files that Claude loads only when a task calls for them. Each skill is built around a SKILL.md file with a short name and description, so Claude knows when to use it without reading everything up front. Skills work in the Claude apps, Claude Code, the Claude API, and the Claude Agent SDK.

Anthropic introduced the idea in its engineering post Equipping agents for the real world with Agent Skills on October 16, 2025. Two months later, on December 18, 2025, it published the format as an open standard at agentskills.io. This explainer covers how skills are built, where they run, how to make one, and what to check before you install someone else’s.

Key Takeaways

  • A skill is a folder with a required SKILL.md file. Its YAML frontmatter needs a name and a description, and the description tells Claude when to use it.
  • Claude loads skills in stages. Only the name and description sit in context at startup (about 100 tokens per skill, per Anthropic’s docs), and the full instructions load only when relevant.
  • Custom skills don’t sync between surfaces. A skill uploaded to claude.ai has to be uploaded again to the API, and Claude Code skills live separately on your filesystem.
  • Anthropic tells you to treat a third-party skill like installing software: use trusted sources, and read every file before you run it.
  • Agent Skills are not covered by zero data retention arrangements and are not HIPAA eligible, according to the developer docs as of November 2026.

What an Anthropic Agent Skill Actually Contains

Anthropic’s engineering team describes skills as “organized folders of instructions, scripts, and resources” that an agent can discover and load as needed. The team compares writing one to putting together an onboarding guide for a new hire. You’re not changing the model. You’re handing a general-purpose agent the procedure and context it needs for one kind of job.

The Agent Skills specification site shows a typical layout like this:

  • SKILL.md (required): metadata plus the instructions
  • scripts/ (optional): code the agent can run
  • references/ (optional): longer documentation
  • assets/ (optional): templates and other resources

The SKILL.md file starts with YAML frontmatter. Anthropic’s Agent Skills overview sets clear limits on the two required fields. The name can be up to 64 characters, using only lowercase letters, numbers, and hyphens, and it can’t contain the reserved words “anthropic” or “claude.” The description can run up to 1,024 characters and should say both what the skill does and when Claude should use it.

That second part matters more than it looks. Claude decides whether to open a skill based mostly on its description, so a vague one (“helps with documents”) gets skipped or misfires.

How Progressive Disclosure Keeps Skills Light

Anthropic calls progressive disclosure “the core design principle that makes Agent Skills flexible and scalable.” Instead of pasting a huge prompt into every conversation, Claude reads a skill in layers. The developer docs list the cost of each layer:

Level When it loads Approximate cost What it includes
1: Metadata Always, at startup About 100 tokens per skill The name and description
2: Instructions When the skill is triggered Under 5,000 tokens The body of SKILL.md
3 and beyond: Resources Only when needed Nothing until accessed Bundled files and scripts

So you can keep many skills installed without filling the context window. A long legal checklist or a 40-page brand guide only costs tokens on the tasks that use it.

Skills Can Run Code, Not Just Hold Text

A skill can include scripts that Claude runs as tools. Anthropic’s example is its PDF skill, which bundles a Python script that pulls the form fields out of a PDF. Claude can run that script without loading either the script or the PDF into context, and only the output comes back.

Why bother with code? Because code gives the same result every time. The engineering post argues that deterministic scripts make a workflow more consistent than asking the model to redo the same steps from scratch.

Where Anthropic Agent Skills Work

Skills run on four main surfaces, but they behave a little differently on each. This table summarizes Anthropic’s developer docs and help center as of November 2026.

Surface Pre-built skills Custom skills Runtime notes
Claude apps (claude.ai) Yes, used automatically when creating documents Uploaded as a zip file; requires code execution to be enabled Network access depends on user or admin settings
Claude API (Developer Platform) Yes: pptx, xlsx, docx, pdf Uploaded through the Skills API (/v1/skills) and shared workspace-wide Requires the code execution tool; no network access and no runtime package installs
Claude Code No pre-built document skills, though an open-source Claude API skill is bundled Plain folders in ~/.claude/skills/ (personal) or .claude/skills/ (project) Full network access, like any program on your computer
Claude Agent SDK Bundled Claude Code skills Files on disk, discovered through the settingSources option No programmatic API to register skills; they must exist as files

On plans, the two official sources describe Anthropic agent skills a little differently. The Claude help center says skills are available on Free, Pro, Max, Ultra, Team, and Enterprise plans with code execution turned on. The developer overview lists custom skill uploads on Pro, Max, Ultra, Team, and Enterprise. If you’re on the Free plan and want to upload your own skill, check your settings under Customize, then Skills, before you build anything.

If you mostly work in the terminal, skills are probably where you’ll feel the biggest change. Our full Claude Code review covers the tool itself; skills are one of the main ways to customize it for your team.

Skills Don’t Sync Between Surfaces

This catches people out with Anthropic agent skills. The developer docs state that custom skills uploaded to claude.ai aren’t available through the API, API uploads don’t appear in claude.ai, and Claude Code skills are separate from both. Say your marketing team builds a brand-voice skill in claude.ai. Your developers will need to upload the same folder through the Skills API, or commit it to the repo, before their tools can see it.

For teams, there’s a sharing path on each surface. API skills are shared across a workspace. Claude Code project skills can be committed to a repository or distributed through plugins. And since December 18, 2025, Team and Enterprise admins can provision skills from admin settings, which Anthropic says are “enabled by default for all users.”

How to Create a Skill (High-Level Steps)

You don’t need to be a developer to write a basic skill. It’s a Markdown file. Here’s the process as Anthropic’s docs and engineering post describe it.

  1. Find a real gap first. Anthropic suggests starting with evaluation: run Claude on representative tasks, note where it struggles or needs the same correction twice, and build the skill around that.
  2. Create a folder and a SKILL.md file. Give it a lowercase, hyphenated name and a description that states what it does and when to use it.
  3. Write the instructions in plain Markdown. The Claude Code docs recommend keeping SKILL.md under 500 lines and moving long reference material into separate files that the skill links to.
  4. Add scripts or templates only if they help. Say clearly whether Claude should run a script or just read it as reference.
  5. Install it where you’ll use it. In Claude Code, place the folder in a skills directory. In claude.ai, upload a zip under Customize, then Skills. On the API, upload it through the Skills API.
  6. Watch how Claude actually uses it, then revise. Anthropic suggests asking Claude to write its successful approaches and common mistakes back into the skill.

You can also skip the blank page. Anthropic’s December 2025 announcement says you can describe a workflow and have Claude build the skill for you, write the instructions yourself, or upload an existing folder.

One technical detail to watch: Claude Code supports extra frontmatter fields, such as disable-model-invocation (so only you can trigger a skill) and allowed-tools. But the Claude Code docs warn that claude.ai uploads and the Skills API accept only name, description, license, compatibility, metadata, and allowed-tools. Other fields cause an error on upload. If you plan to share one skill across surfaces, stick to that shorter list.

The Open Standard: What’s Confirmed and What Isn’t

Anthropic published Agent Skills as an open standard on December 18, 2025. The announcement on the Claude blog says skills “should be portable across tools and platforms,” and the specification now lives at agentskills.io.

Here’s a quick breakdown of what the official sources support:

  • Confirmed: the format was originally developed by Anthropic and released as an open standard, with development open to contributions on GitHub, according to agentskills.io.
  • Confirmed: Claude Code’s own docs say its skills follow the Agent Skills standard, and that Claude Code adds extras like invocation control and subagent execution on top.
  • Confirmed: partner skills from Notion, Canva, Figma, and Atlassian were part of the December 2025 skills directory launch.
  • Unclear: how consistently other agent products implement the spec. The standard site says it has been adopted by “a growing number of agent products,” but a skill that leans on Claude Code-only fields won’t necessarily behave the same elsewhere.

The practical takeaway: write portable skills with the core fields, and test them in each tool before you rely on them.

Security: Treat a Skill Like Software You’re Installing

A skill can tell Claude to run code and call tools. That’s the point, and it’s also the risk. Anthropic’s engineering post warns that malicious skills could introduce vulnerabilities or direct Claude to exfiltrate data or take unintended actions. The developer docs go further: use skills only from trusted sources, meaning ones you created or ones from Anthropic.

Before you install a third-party skill, run through this checklist based on Anthropic’s guidance:

  • Read the whole SKILL.md, not just the description.
  • Open every bundled script, image, and resource file, and look for network calls or file access that don’t match the stated purpose.
  • Check code dependencies. Anthropic notes that even a trusted skill can be compromised if an external dependency changes.
  • Be extra careful with skills that fetch content from external URLs, since fetched pages can carry malicious instructions.
  • Keep untested skills away from production systems and sensitive data.

Enterprise organizations get one extra layer. Claude Enterprise admins can turn on skill content scanning for custom skills uploaded in claude.ai and the Claude Cowork desktop agent. The docs are clear that this scanning doesn’t cover skills uploaded through the Skills API or the Claude Console, so API teams still need their own review step.

The same logic applies to agents generally. If you’re weighing how much access to give any autonomous tool, our roundup of safer AI agent options covers the permission questions worth asking.

Practical Use Cases for Agent Skills

Anthropic agent skills fit best when you keep explaining the same process to Claude. The Claude help center lists examples like these:

  • Applying brand style guidelines to documents and presentations
  • Drafting emails from company templates
  • Formatting meeting notes in your company’s structure
  • Creating tasks in tools like Jira, Asana, or Linear
  • Running a company-specific data analysis workflow

Anthropic’s own pre-built skills handle Word, Excel, PowerPoint, and PDF files. Partner quotes in the December 2025 announcement point to other directions: Vercel says it built a deploy skill alongside the Claude team, and Atlassian says its skills help turn specs into backlogs.

A realistic example: a three-person agency writes one skill holding its client report template, tone rules, and a script that formats tables. Every report request then follows the same structure, and new hires don’t need to learn the template by memory. If you’re mapping out where steps like this belong, our guide to designing AI workflows helps you decide which parts need a human check.

Skills, MCP, and Prompts Do Different Jobs

A common mix-up is treating skills as a replacement for the Model Context Protocol (MCP). They solve different problems. MCP connects Claude to outside tools and data. Skills teach Claude a procedure, which can include how to use those tools well. Anthropic’s engineering post says it’s exploring how skills can complement MCP servers, and Zapier’s quote in the December announcement describes pairing skills with its MCP tools. For what MCP connections look like in practice, see these practical Zapier MCP use cases.

And a prompt? A prompt applies to one conversation. A skill sits on standby across many conversations and loads itself when the task matches.

Should You Build an Anthropic Agent Skill or Install One?

Start by building one small skill yourself. Pick a task you’ve explained to Claude at least three times, write a clear description, and keep the first version short. That gives you a feel for how Claude triggers skills, with zero security risk.

Install third-party skills only after you’ve read every file, and prefer Anthropic’s own or a verified partner’s. If your team works across claude.ai, the API, and Claude Code, plan for the fact that skills don’t sync, and keep one source folder in version control. Used that way, Anthropic agent skills are a low-cost way to make Claude follow your process instead of a generic one.

FAQ

Can Claude create a skill for me?

Yes. Anthropic’s December 2025 announcement says you can describe a workflow and have Claude build the skill. In Claude Code, Anthropic also offers a skill-creator plugin that can test a skill against example cases and compare results with and without it. You should still read and edit what Claude writes before you rely on it.

Do Agent Skills work with tools other than Claude?

The format is designed to. Agent Skills is an open standard hosted at agentskills.io, and the site says it has been adopted by a growing number of agent products. Support varies by tool, though, so a skill that uses Claude Code-only frontmatter fields may not behave the same way elsewhere. Test portable skills in each tool.

Are Agent Skills covered by zero data retention?

No. Anthropic’s developer docs state that Agent Skills are not covered by zero data retention (ZDR) arrangements. Skill definitions and execution data follow Anthropic’s standard retention policy, and the feature is not HIPAA eligible as of November 2026. Teams handling regulated data should factor that in before uploading skills that touch sensitive files.

Do skills replace custom slash commands in Claude Code?

Mostly, yes. The Agent SDK docs call skills the recommended successor to custom command files in .claude/commands/, but those older files keep working. A skill can also be triggered directly by typing /skill-name, so you get both automatic and manual use from one folder.

Can a skill access the internet?

It depends on where it runs. On the Claude API, skills have no network access and can’t install packages at runtime. In Claude Code, they have the same network access as any program on your computer. In the Claude apps, network access depends on your user or admin settings.

Harry covers artificial intelligence for AI Journal Now.

Related Articles

Harry

Harry is the Founder and Editor of AI Journal Now, where he researches and writes about artificial intelligence, AI tools, generative AI, automation, and AI search. His work focuses on analyzing AI platforms, reviewing AI software, comparing AI solutions, and tracking how AI search is changing the way people find information. He also builds and refines AI prompt systems for research, writing, and SEO, which shapes how he evaluates AI writing and content tools. Through AI Journal Now, Harry publishes research-driven reviews, comparisons, and practical guides to help readers decide which AI tools are worth their time and money.

Leave a Reply

Your email address will not be published. Required fields are marked *