What are Claude Skills? Agent Skills Guide

What Skills Are — More Than Prompt Templates

It's a common misconception to think Skills are just "prepared prompts" — in reality, Skills are far more powerful:

• A folder, not a single file — contains SKILL.md + scripts + assets + reference materials
• Has runnable scripts — Skills can call Python, Bash, or other tools through the Bash tool
• Bundles data/templates — can include JSON, CSV, sample files, brand guidelines, etc.
• Auto-trigger — Claude picks the Skill itself when the task matches the whenToUse declaration
• Cross-platform — write the Skill once and use it on Claude.ai, Claude Code, and the API

Skill Folder Structure

The basic structure of a Skill folder looks like this:

my-skill/
├── SKILL.md                # The main file — instructions + frontmatter
├── scripts/
│   ├── generate.py         # Scripts Claude can run
│   └── validate.sh
├── templates/
│   ├── invoice.html        # Pre-built templates
│   └── report.docx
├── reference/
│   └── brand-guide.md      # Reference materials
└── assets/
    ├── logo.png
    └── colors.json

Claude reads SKILL.md first, then opens additional files as the instructions tell it, or runs scripts as specified.

SKILL.md Format — YAML Frontmatter

SKILL.md is a Markdown file with YAML frontmatter at the top — this metadata is what the system uses to decide when to load this Skill:

---
name: invoice-generator
description: Generate invoices following the company brand guideline
whenToUse: when the user asks to create an invoice, bill, or tax invoice
---

# Invoice Generator

## How it works
1. Read templates/invoice.html
2. Substitute values from user input
3. Use assets/logo.png + colors.json
4. Run scripts/generate.py to render as PDF

## Example
```
User: "Create an invoice for customer ABC for 50,000 baht"
Claude: [load template, generate PDF, return file]
```

Field	Required	Purpose
name	Yes	Skill identifier — used in slash commands (e.g. /invoice-generator)
description	Yes	A brief description — shown in the available skills list
whenToUse	Yes (for auto-trigger)	The criterion Claude uses to decide whether to load this Skill
license	No	License of the Skill (MIT, Apache, etc.)
version	No	Semver of the Skill

Progressive Disclosure — Doesn't Eat the Context Window

Before Skills 2.0, every Skill instruction was loaded into the context window the moment the Skill was activated — exhausting context fast. Skills 2.0 fixes this with Progressive Disclosure:

1. Stage 1 — Discovery — Claude only sees name + description for all Skills (~50 tokens per Skill)
2. Stage 2 — Match — when the user sends a prompt, Claude compares it against each Skill's whenToUse
3. Stage 3 — Load — fully loads SKILL.md for the matching Skill (only the one to be used)
4. Stage 4 — Drill Down — if SKILL.md references other files (scripts, templates), Claude opens only what's needed

The result: users can install hundreds of Skills at once without exhausting the context window — because each session loads only the Skills actually used.

How Skills Trigger — Two Methods

Method	Detail	Best For
Slash Command	User types /skill-name — Claude opens that Skill immediately	Tasks where the user knows which Skill they want
Auto-trigger	Claude reads the prompt → matches against whenToUse → opens the matching Skill automatically	Tasks where the user just states a need without knowing which Skill applies

Installing a Skill

Skills can be installed several ways — using the npx skills CLI is simplest:

# Install a Skill from a GitHub repo
npx skills add <org>/<repo>

# Install an official Anthropic Skill
npx skills add anthropics/claude-code -- skill frontend-design

# Manual: copy the folder into the skills directory
cp -r my-skill ~/.claude/skills/

# Claude.ai: Settings > Capabilities > Skills > Upload

Where Claude looks for Skills depends on the surface in use:

Surface	Skills Directory
Claude.ai (Web)	Settings > Capabilities > Skills (upload zip)
Claude Code (CLI)	~/.claude/skills/ (user-level), ./.claude/skills/ (project-level)
Claude API	Via the tools parameter in the Messages API
thClaws	~/.thclaws/skills/ (supports the same SKILL.md format)

Skills 2.0 — A Major Upgrade in 2026

In Q1 2026, Anthropic shipped "Skills 2.0", which transformed Skills from "prompt templates" into "complete workflow packages":

Item	Skills 1.0 (old)	Skills 2.0 (new)
Form	A single markdown file	A folder with scripts, templates, and reference materials
Context	Loaded entirely up-front	Progressive Disclosure (multi-x context savings)
Behavior	Just instructions for the AI to follow	Run real scripts + use templates + access assets
Cross-platform	Each surface had a different format	One format — works on Claude.ai/Code/API

Writing Your Own Skill — Minimum Viable Skill

The smallest functional Skill needs only a single file:

# ~/.claude/skills/git-cleanup/SKILL.md
---
name: git-cleanup
description: Delete merged branches and prune the remote
whenToUse: when the user asks to clean up branches, cleanup git, or delete stale branches
---

# Git Cleanup Skill

Run these steps:
1. Fetch the latest remote: `git fetch --all --prune`
2. Find branches merged into main: `git branch --merged main`
3. Delete local branches that are merged (excluding main, master, develop)
4. Show a summary: deleted N branches

After completing, report the results to the user

That's all you need — the user can invoke it via slash command (/git-cleanup) or by speaking naturally ("Help me clean up the merged branches"). Claude will trigger this Skill automatically.

Skills vs MCP — Which Should You Use?

Topic	Skills	MCP
Purpose	Pre-built workflows (how to do something)	Tool integration (connect to external systems)
Contents	Instructions + scripts + assets	API endpoints (tools, resources, prompts)
Used Together	A higher-level layer — can use MCP tools internally	A primitive that Skills call
Examples	"frontend-design", "git-cleanup", "code-review"	"github MCP", "slack MCP", "postgres MCP"

Summary — Claude Skills in One Paragraph

Topic	Summary
What it is	A folder bundling instructions + scripts + assets that Claude loads to perform specialized tasks
Core file	SKILL.md + YAML frontmatter (name, description, whenToUse)
What's new in Skills 2.0	Progressive Disclosure (no context bloat), full workflow packages, cross-platform
Trigger	Slash command (/skill-name) or auto-detect via whenToUse
Install	npx skills add <org>/<repo> or copy into ~/.claude/skills/
Where	Claude.ai, Claude Code, API — and thClaws

Skills 2.0 lets AI agents "learn" an organization's workflows in a portable way — write once and use everywhere, across every surface, every team, and every supporting agent.

- Saeree ERP Team

Read More — Related Articles

• Claude MCP: What is Model Context Protocol — A Complete Deep Dive
• thClaws: A Thai-Made AI Agent Workspace That Supports Skills
• Source Leak: Claude Code Source Code Leak: 512,000 Lines

References

• GitHub — anthropics/skills (Public Skills Repository)
• Claude API Docs — Agent Skills Overview
• Claude Code Docs — Extend Claude with Skills
• Claude Help Center — What are Skills?
• Anthropic — Introduction to Agent Skills (Course)