What Are Claude Agent Skills? The Beginner’s Guide (Install, Use, and Write Your Own)

CodexFuse Team · 2026-11-04T09:05:47.988Z · 9 min read min read

Claude Agent Skills explained for beginners: what SKILL.md is, progressive disclosure, install paths, auto-invocation, skills vs MCP, and writing your own skill.

Claude Agent Skills are reusable folders of instructions, scripts, and resources that teach Claude how to do one specific job well — once. Instead of pasting the same long prompt into every conversation, you package the procedure as a skill, and Claude loads it automatically whenever a task matches. Anthropic's platform documentation puts it this way: "Skills are reusable, filesystem-based resources that give Claude domain-specific expertise: workflows, context, and best practices that turn a general-purpose agent into a specialist." If you have ever wondered what are Claude Agent Skills and whether they are worth your time, this guide covers the whole picture: what a skill is, the loading mechanism that keeps skills cheap, how to install and invoke them, how they differ from MCP, and how to create your own. Want to try one right away? Browse our AI Skills Library, a searchable collection of ready-to-use skills you can turn into copy-paste prompts in seconds.

What Are Claude Agent Skills, Exactly?

An Agent Skill is a folder containing a SKILL.md file — instructions plus a short YAML header — with optional scripts, templates, and reference files that Claude loads on demand to become a specialist at one task. Anthropic's launch announcement frames it memorably: "Think of Skills as custom onboarding materials that let you package expertise, making Claude a specialist on what matters most to you." The Help Center version is plainer: "Skills are folders of instructions, scripts, and resources that Claude loads dynamically to improve performance on specialized tasks."

That is Claude skills explained in one paragraph: a folder, a Markdown file, and a description that tells Claude when to reach for it. Anthropic introduced Agent Skills on October 16, 2025, shipping four pre-built document skills — PowerPoint, Excel, Word, and PDF (skill IDs pptx, xlsx, docx, pdf) — as the proof of concept. The launch pitched four properties: composable ("Claude automatically identifies which skills are needed and coordinates their use"), portable ("Build once, use across Claude apps, Claude Code, and API"), efficient ("Only loads what's needed, when it's needed"), and powerful ("Skills can include executable code for tasks where traditional programming is more reliable than token generation").

How Do Claude Skills Actually Work?

Skills stay cheap through progressive disclosure: Claude preloads only each skill's name and description — about 100 tokens per skill — and loads the full instructions only when your task matches. Until a skill is triggered, only its metadata occupies context, so you can install many skills without a context penalty.

The engineering post's punchline is that "the amount of context that can be bundled into a skill is effectively unbounded" — Level 1 is always tiny, and everything below it is pay-as-you-go. That is the whole trick: skills give Claude deep expertise without the deep token bill, because the deep part only loads when it earns its place.

Claude Skills vs MCP: What's the Difference?

MCP connects Claude to outside tools and data; a skill teaches Claude the repeatable procedure to follow. They complement each other — they are never rivals, and you will often use both in the same task. Anthropic's engineering post states the relationship directly: "Skills can complement Model Context Protocol (MCP) servers by teaching agents more complex workflows that involve external tools and software." If you want the protocol side of the story, read our Model Context Protocol guide first.

How to Use Claude Skills

Install a skill, then just ask Claude in plain language — it matches your request to the skill's description and loads the skill automatically, with no manual selection. If you would rather be explicit, invoke it directly with /skill-name: the skill's name field becomes its slash command. The Claude Code documentation states it verbatim: "Claude uses skills when relevant, or you can invoke one directly with /skill-name." Newcomers to the terminal workflow should start with our Claude Code beginner guide before installing anything.

One caveat worth knowing before you invest time: custom skills do not sync across surfaces. A skill uploaded on claude.ai must be uploaded separately to the API, and Claude Code skills live on your filesystem — plan for one install per surface.

Where Do Agent Skills Work?

Skills run on Claude.ai, in Claude Code, through the Claude Agent SDK, and on the Developer Platform — and since December 18, 2025, the format is an open standard, so the same skill folder now works in other agent products too. The standard lives at agentskills.io, which describes it as "originally developed by Anthropic, released as an open standard, and has been adopted by a growing number of agent products." Verified adopters include Cursor (Agent Skills support shipped in version 2.4 on January 22, 2026), the OpenAI Codex CLI, Gemini CLI (stable skills support in v0.26.0), Cline (behind an experimental Settings toggle), and Google Antigravity. The Claude Code documentation confirms the portability promise: "Claude Code skills follow the Agent Skills open standard, which works across multiple AI tools."

Skills also show up inside always-on agents: products like OpenClaw consume skills as part of their agent loop, so the same SKILL.md you write for Claude Code can travel with you. If that style of agent interests you, our OpenClaw beginner guide is the natural next read.

How to Create Your Own Claude Skill

Write a SKILL.md file with a name and a description in YAML frontmatter, put it in a folder under ~/.claude/skills, and Claude starts matching it automatically. If you would rather be interviewed than edit files, install the skill-creator skill: it asks about your workflow, generates the folder structure, formats the SKILL.md, and bundles the resources — no manual file editing required.

The frontmatter rules are strict and worth memorizing. The name may be at most 64 characters, lowercase letters, numbers, and hyphens only — no reserved words anthropic or claude — and it must match the parent folder's name. The description must be non-empty, at most 1,024 characters, and it must say both what the skill does and when Claude should use it, because the description is the entire basis for automatic matching. Here is a minimal original example:

---
name: changelog-writer
description: Draft a changelog entry from git commits. Use when the user asks for release notes or a changelog after merging changes.
---
# Changelog Writer

1. Run `git log` for the range the user names (default: since the last tag).
2. Group commits by type: Features, Fixes, Docs.
3. Write one bullet per change, in plain past tense, no hype words.
4. Ask before publishing; never push to a remote.

Add scripts/, references/, or assets/ folders beside the file when the skill needs more than instructions — a validation script, a company template, a style reference. One safety habit before you share anything you wrote: skills are executable instructions, so treat a downloaded skill like code you downloaded. Scan community skills before installing them, exactly as our SkillSpector beginner guide walks through.

Sources

• Agent Skills — Claude Platform Docs (platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) — official definition, progressive disclosure levels, frontmatter rules, install paths, the no-sync-across-surfaces caveat; fetched 2026-11-04.
• Introducing Agent Skills (claude.com/resources/articles/skills) — October 16, 2025 launch, the four document skills, composable/portable/efficient/powerful claims, skill-creator, the December 18, 2025 open-standard update; fetched 2026-11-04.
• Equipping agents for the real world with Agent Skills (anthropic.com/research/equipping-agents-for-the-real-world-with-agent-skills) — engineering post, October 16, 2025 (updated October 18, 2026), skills-complement-MCP phrasing; fetched 2026-11-04.
• What are skills? — Anthropic Help Center (support.claude.com/en/articles/12512176-what-are-skills) — plain-language definition; fetched 2026-11-04.
• Use skills in Claude — Anthropic Help Center (support.claude.com/en/articles/12512180-use-skills-in-claude) — claude.ai setup, automatic invocation; fetched 2026-11-04.
• Claude Code skills documentation (code.claude.com/docs/en/skills) — filesystem discovery paths, the "invoke with /skill-name" phrasing, open-standard confirmation; fetched 2026-11-04.
• anthropics/skills — GitHub repository (github.com/anthropics/skills) — README definition, plugin install commands, template directory; 187,223 stars and 22,091 forks as fetched 2026-11-04.
• Agent Skills open standard (agentskills.io) — standard home, folder layout, cross-product adoption statement; fetched 2026-11-04.
• Cross-Agent Skills: Portability in 2026 (mcp.directory) — third-party roundup quoting each vendor's own changelog/docs for Cursor 2.4, OpenAI Codex CLI, Gemini CLI v0.26.0, Cline, and Google Antigravity; fetched 2026-11-04.

Frequently Asked Questions

Do I need to know how to code to use Claude Agent Skills?

No. Using a skill means installing a folder or enabling it in settings, then describing your task in plain language — Claude does the matching. Writing your own skill is writing Markdown instructions, not code, and the skill-creator skill interviews you through the whole process.

Are Claude Agent Skills free?

The format itself is free and open — anyone can write a SKILL.md and share it. Using skills depends on the surface: on claude.ai, custom skills need a paid plan with code execution enabled, while the pre-built document skills work where they are offered; in Claude Code and the API, skills ride on your existing subscription or API usage.

How are Agent Skills different from slash commands?

A slash command is manual — you type it. A skill's description lets Claude invoke it automatically when your request matches, which is the whole point of progressive disclosure. The skill's name does double duty as its slash command, so /skill-name is the manual override, not the primary interface.

Can one skill work in both Claude Code and Cursor?

Yes — that is what the December 18, 2025 open standard is for. A skill is just a folder with a SKILL.md file, so the same folder works in Claude Code, Cursor 2.4+, Gemini CLI, Cline, and other adopting products without modification.

Are Agent Skills safe to install from strangers?

Treat them like code: a skill can bundle executable scripts, so only install skills from sources you trust, read the SKILL.md before installing, and never put API keys or tokens in a skill file. Run community skills through a scanner before you install them.