Claude Skills: The Complete Guide
What they are, how they work, and how to create, install, and use one. A practical guide for developers who want to teach their agent new tricks.
In short: a Claude Skill is a folder with a SKILL.md file that teaches an AI agent how to do a specific task. Skills follow the open Agent Skills standard introduced by Anthropic, and the same skill works across the Claude API, Claude Code, and other agents. This guide covers the format, how to write one, and how to install and use them, with worked examples. For the vendor-neutral view across every supported agent, see the Agent Skills guide.
What are Claude Skills?
A skill is a directory that contains a required SKILL.md file plus optional bundled resources. The SKILL.md has two parts: YAML frontmatter that tells the agent when to use the skill, and Markdown instructions the agent follows when it does. A typical layout looks like this:
my-skill/
├── SKILL.md # required: frontmatter + instructions
├── scripts/ # optional: executable code
├── references/ # optional: docs loaded as needed
└── assets/ # optional: templates, icons, fontsThe agent pre-loads every installed skill’s name and description into its system prompt. When a task matches, it reads the full SKILL.md and follows the instructions, running bundled scripts or reading references only as needed. That is why an agent can keep many skills on hand with a small context footprint. For the full standard, see agentskills.io and the anthropics/skills repository.
How Claude Skills work: progressive disclosure
Level 1: Metadata
The name and description (about 100 words) are always in the agent context, so it knows when a skill applies without loading the whole thing.
Level 2: SKILL.md body
When a task matches the description, the agent reads the full instructions. Keep this under 500 lines.
Level 3: Bundled resources
Scripts, references, and assets load only when the instructions call for them, so a skill can carry a lot without bloating context.
Claude Skills vs Claude Code skills
These get used interchangeably, so here is the distinction. Agent Skills is the underlying open standard. "Claude Skills" usually means that standard as used across Claude apps. "Claude Code skills" means the same skills running inside the Claude Code agent. The SKILL.md format does not change. Claude Code is simply one host that can install and run a skill, alongside other agents that support the standard.
How to create a Claude Skill
Create a folder, add a SKILL.md, and write frontmatter plus instructions. The single most important field is the description, because it is the trigger. Make it assertive about both what the skill does and when to use it, since a vague description means the agent never reaches for the skill. Keep the body under 500 lines and push heavy detail into bundled resources. Here is a minimal example:
--- name: add-esignature description: Add TurboSign e-signatures to an app. Use when the user wants to send a document for signature, collect a signature, or add signing. --- # Add E-Signatures 1. Detect the project language and install the TurboDocx SDK. 2. Read the API key from the environment, never hardcode it. 3. Call TurboSign to send the document and return the signing link.
Use the official skill-creator skill
The fastest way to write a good skill is to let a skill do it. Anthropic publishes an official skill-creator skill that runs a guided loop: it captures what you want the skill to do and when it should trigger, interviews you on edge cases and output format, writes the SKILL.md, then tests it with evals and helps you refine the description for better triggering. It is the recommended starting point for any new skill.
For a hands-on walkthrough, see our guide to building a Claude Code skill from scratch.
How to install and use Claude Skills
You can install a community skill with the open-source skills CLI, or drop a SKILL.md folder into your agent’s skills directory (for example .claude/skills/ for Claude Code, .cursor/skills/ for Cursor). As a worked example, this one command installs the TurboDocx Quickstart Skill, which teaches your agent to add e-signatures and document generation to a project:
npx skills add TurboDocx/quickstart
Once installed, the agent surfaces the skill and invokes it automatically when your request matches its description. You can also call it by name. See how this plays out end to end in our add e-signatures with Claude Code guide.
Claude Skills examples
A few skills that show the range, from authoring to real product work:
- skill-creator: the official Anthropic skill for writing and testing other skills.
- Document and e-signature skills: a skill can wrap a real API. The TurboDocx Quickstart Skill installs the SDK and writes a working integration so your agent can generate documents and send them for signature. This is the kind of latent-demand task skills are great at: take something developers already do by hand and make the agent do it.
- Repo conventions: skills that encode how your team writes code, similar in spirit to a CLAUDE.md file.
Frequently asked questions
What are Claude Skills?
Claude Skills (part of the open Agent Skills standard at agentskills.io) are folders that teach an AI agent how to do a specific task. Each skill is a directory with a SKILL.md file that contains YAML frontmatter (a name and a description) plus Markdown instructions, and optional bundled scripts, references, and assets. The agent loads a skill only when a task matches its description.
What is the difference between Claude Skills and Claude Code skills?
Agent Skills is the underlying standard. "Claude Skills" usually refers to that standard across Claude apps, and "Claude Code skills" refers to using the same skills inside the Claude Code agent. The SKILL.md format is the same. Claude Code is one of several hosts that can install and run a skill.
How do I create a Claude Skill?
Create a folder with a SKILL.md file. Add YAML frontmatter with a name and a clear, assertive description of what the skill does and when to use it, then write the instructions in Markdown. Keep SKILL.md under 500 lines and move heavy material into scripts, references, or assets. Anthropic publishes an official skill-creator skill that walks you through capturing intent, writing the SKILL.md, and testing it.
How do I install and use Claude Skills?
Install community skills with the open-source skills CLI (for example, npx skills add owner/repo), or place a SKILL.md folder in your agent's skills directory such as .claude/skills/. Once installed, the agent surfaces the skill and invokes it automatically when a task matches its description.
Are Claude Skills free and open?
The Agent Skills format is an open standard documented at agentskills.io, and Anthropic's official skills are open source on GitHub. Many third-party skills, including the TurboDocx Quickstart Skill, are MIT licensed and free to install.
Related resources
Build a Claude Code Skill from Scratch →
The hands-on tutorial, with a worked example.
Best Claude Code Skills, Plugins & MCP Servers →
A curated toolkit for getting more from your agent.
AI Engineering Guide →
Ship backend features with AI coding agents.
The Developer's Guide to CLAUDE.md →
Steer your agent with a project context file.
Agent Skills: The Open Standard →
The same format, across every agent that supports it.
Loop Engineering →
Designing the feedback loop your agent runs inside.
All Developer Guides →
Every how-to in one browsable index.
Alex Martinez
Developer Relations & Automation Lead
Try a Claude Skill in your own project
Install the TurboDocx Quickstart Skill and have your agent add e-signatures or document generation in minutes. Your first 5 signatures each month are free.