A Claude Skill (Agent Skills) teaches Claude the steps, context, and best practices for a specific task using a single folder that contains a SKILL.md file. What Skills are and how to use them is covered in the Claude Code Skills guide; this article focuses on the hands-on process of building your own Skill from scratch — creating the folder, filling in the frontmatter, writing the instructions, and installing it — based on Anthropic's official documentation.
The minimum a Skill needs
A Skill is just a folder plus a SKILL.md file inside it. SKILL.md alone is enough to work; everything else (extra docs, scripts, resources) is optional. SKILL.md has two parts — the YAML frontmatter at the top (metadata Claude uses to decide when to use the Skill) and the Markdown body below it (the actual instructions to follow).
Why it works this way — three-level progressive disclosure
The core design of Skills is progressive disclosure: instead of loading everything at once, Claude pulls only the level a task needs into context.
| Level | When loaded | Token cost | Content |
|---|---|---|---|
| Level 1 · Metadata | Always (at startup) | ~100 tokens per skill | name and description from frontmatter |
| Level 2 · Instructions | When the Skill triggers | Under 5k tokens | SKILL.md body (instructions and guidance) |
| Level 3 · Resources | As needed | Effectively unlimited | Bundled files run via bash; contents don't enter context |
This means you can install dozens of Skills while only the names and descriptions (~100 tokens each) sit in context, with the body loaded only when that Skill is actually needed.
Step 1 — Create the folder and SKILL.md
Create a folder named after the Skill and put a SKILL.md inside.
my-skill/
└── SKILL.mdA basic SKILL.md skeleton looks like this.
---
name: my-skill
description: Brief description of what this Skill does and when to use it
---
# My Skill
## Instructions
[Clear, step-by-step guidance for Claude to follow]
## Examples
[Concrete examples of using this Skill]Step 2 — Write the frontmatter (the most important part)
There are only two required fields: name and description. Claude reads these two lines at session startup to decide when to use the Skill, so their quality makes or breaks it. The official constraints are:
- name: max 64 characters, lowercase letters, numbers, and hyphens only, no XML tags, and the reserved words
anthropicandclaudeare not allowed. - description: must be non-empty, max 1024 characters, no XML tags. It must cover both what the Skill does and when Claude should use it.
In particular, pack the description with concrete trigger keywords. For a PDF-processing Skill, for example:
description: Extract text and tables from PDF files, fill forms, merge documents.
Use when working with PDFs, forms, or document extraction, or when the user mentions PDFs.Step 3 — Write the body (instructions)
The body holds the procedures, best practices, and examples Claude should follow. Clear steps and concrete input/output examples are key. The official docs recommend keeping the body concise (roughly under 500 lines) and splitting longer content into separate files that you link to.
Step 4 — Bundle resources and scripts (optional)
A Skill folder can ship extra documents, scripts, and reference materials alongside SKILL.md.
pdf-skill/
├── SKILL.md (main instructions)
├── FORMS.md (form-filling guide)
├── REFERENCE.md (detailed reference)
└── scripts/
└── fill_form.pyThese files load only when referenced. Scripts in particular are run by Claude via bash and return only their output, so the script code itself never consumes context. That's why you can bundle huge references or datasets at effectively zero token cost when they go unused.
Installing and using your Skill
Each surface installs Skills differently. Per the official docs, custom Skills do not sync across surfaces, so you upload them separately wherever you want to use them.
- Claude Code: filesystem-based. Put the Skill folder in
~/.claude/skills/(personal) or.claude/skills/(project) and Claude discovers it automatically — no upload needed. - claude.ai: zip the Skill folder and upload it under Settings > Features. Available on Pro, Max, Team, and Enterprise plans with code execution enabled, applied per individual user (no org-wide sharing or central admin management).
- Claude API: upload via the
/v1/skillsendpoints, then reference theskill_idin thecontainerparameter together with the code execution tool. The beta headerscode-execution-2025-08-25,skills-2025-10-02, andfiles-api-2025-04-14are required. Uploaded custom Skills are shared workspace-wide.
Note that Claude also ships pre-built Skills such as PowerPoint (pptx), Excel (xlsx), Word (docx), and PDF (pdf), which are used automatically during document tasks with no setup.
Authoring tips (best practices)
- Make the description specific: state both "what" and "when," and include enough trigger keywords so Claude reaches for the Skill at the right moment.
- Keep SKILL.md lean: split a long body into reference files and link them. Add a table of contents to reference files longer than 100 lines.
- Push deterministic work into scripts: rather than regenerating code each time, package repetitive steps like validation or conversion as scripts — more reliable and token-efficient.
- Include examples: concrete input/output examples help Claude follow the Skill accurately.
Security note
As a rule, use Skills only from trusted sources — ones you created yourself or obtained from Anthropic. Skills give Claude the ability to invoke tools and execute code, so a malicious Skill can lead to data exfiltration or unauthorized access. Audit the SKILL.md, scripts, and resources of any Skill whose origin is unclear, and be especially careful with Skills that fetch data from external URLs. Treat it with the same caution as installing software.
Wrap-up
Creating a Skill boils down to putting a SKILL.md in a folder and writing good frontmatter (name and description) and instructions. The fastest path is to start small and refine the description and instructions as you actually use it. For complete authoring guidance, see Anthropic's official docs (Agent Skills overview, best practices).