Agent Skills

> A standardized way to give AI agents new capabilities and expertise. Skills are instruction sets that teach AI agents how to work — providing context, guidelines, and step-by-step procedures for specific tasks.

How Skills Work

✏️ SKILL CREATOR
Writes SKILL.md with name, description, and instructions in a skill directory
└── skill-name/SKILL.md (YAML frontmatter + Markdown instructions)
↓
🔍 AGENT DISCOVERS & ACTIVATES THE SKILL
Agent scans skill directories → reads name + description → loads SKILL.md on match
Progressive disclosure: agent stores 100+ skills, loads only the one that matches
↓
⚡ AGENT EXECUTES THE SKILL
Follows instructions → runs tools/commands → produces output
Can reference scripts/, references/, assets/ in the skill directory
📁 skill-name/
├── SKILL.md
├── scripts/
├── references/
└── assets/

Contents

What is an Agent Skill

An Agent Skill is a set of instructions that teaches an AI agent how to perform a specific task. Skills are written in Markdown with YAML frontmatter and stored in a standardized directory structure.

Aspect Description
What it is Instructions that teach an agent how to work
Format SKILL.md with YAML frontmatter + Markdown body
Scope Task-specific (e.g., "how to process PDFs")
Discovery Agent scans default skill directories on startup
Activation Agent loads skill when user query matches its description
Execution Agent follows instructions, can run scripts/commands

Skill vs Tool vs MCP

Concept Teaches the agent... Analogy
Skill How to do something A recipe book
Tool What it can do A kitchen appliance
MCP What data it can access A pantry

Skills are portable — the same skill works in VS Code with GitHub Copilot, Claude Code, OpenCode, Gemini CLI, and any other agent that supports the Agent Skills format.

Specification

The Agent Skills specification defines a standard format for skills that works across all compatible AI agents.

SKILL.md Format

Each skill lives in its own directory with a SKILL.md file containing YAML frontmatter followed by Markdown content.

Frontmatter fields:
Field Required Constraints
name Yes Max 64 chars. Lowercase letters, numbers, hyphens only. Must match directory name
description Yes Max 1024 chars. Describes what the skill does and when to use it
license No License name or reference to bundled license file
compatibility No Max 500 chars. Environment requirements
metadata No Arbitrary key-value mapping for additional metadata
allowed-tools No Space-separated string of pre-approved tools (experimental)
Example: 
---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"




Instructions



To process PDFs, use pdfplumber for text extraction...

Skill Directory Structure

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code (bash, python, etc.)
├── references/       # Optional: documentation, examples, specs
├── assets/           # Optional: templates, resources, images
└── ...

The SKILL.md file is the only required file. All other directories are optional and provide supporting context the agent can reference.

All Skills Reference

All skills below follow the Agent Skills specification and can be installed in any compatible tool.

Table of Contents

# Skill Source Category Description
1 algorithmic-art Anthropic Design Create algorithmic art with p5.js & seeded randomness
2 brand-guidelines Anthropic Design Apply brand colors and typography to artifacts
3 canvas-design Anthropic Design Create beautiful visual art in .png/.pdf
4 claude-api Anthropic Development Build, debug, optimize Claude API / Anthropic SDK apps
5 doc-coauthoring Anthropic Writing Co-author documentation with structured workflow
6 docx Anthropic Document Read/write/edit .docx files
7 frontend-design Anthropic Design Create production-grade frontend interfaces
8 internal-comms Anthropic Writing Write internal communications with company formats
9 mcp-builder Anthropic Development Create MCP servers for external API integration
10 pdf Anthropic Document Extract PDF text, tables, forms using pdfplumber
11 pptx Anthropic Document Create/manipulate .pptx slide decks
12 skill-creator Anthropic Development Create, edit, optimize, and evaluate skills
13 slack-gif-creator Anthropic Design Create animated GIFs optimized for Slack
14 theme-factory Anthropic Design Style artifacts with 10 pre-set themes
15 web-artifacts-builder Anthropic Development Build and deploy web artifacts
16 webapp-testing Anthropic Testing Test local web apps with Playwright
17 xlsx Anthropic Document Read/write/edit .xlsx spreadsheets
18 caveman Community Development Agent-centric workflow orchestration
19 spec-kit Community Development Specification-driven development tools
20 agency-agents Community Development Multi-agent orchestration framework

Anthropic Skills

Official skills from Anthropic's skills repository. These cover common development, design, and document tasks.

1. algorithmic-art — Creating algorithmic art using p5.js with seeded randomness
  • GitHub: anthropics/skills/skills/algorithmic-art
  • Description: Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use when users request creating art using code.
  • Category: Design
  • Install: git clone or manual copy to .agents/skills/algorithmic-art/
git clone https://github.com/anthropics/skills.git
cp -r skills/algorithmic-art /your-project/.agents/skills/
2. brand-guidelines — Applies Anthropic's official brand colors and typography
  • GitHub: anthropics/skills/skills/brand-guidelines
  • Description: Applies Anthropic's official brand colors and typography to any sort of artifact. Use when brand colors or style guidelines apply.
  • Category: Design
3. canvas-design — Create beautiful visual art in .png and .pdf documents
  • GitHub: anthropics/skills/skills/canvas-design
  • Description: Create beautiful visual art in .png and .pdf documents using design philosophy. Use when creating posters, pieces, or visual designs.
  • Category: Design
4. claude-api — Build, debug, and optimize Claude API / Anthropic SDK apps
  • GitHub: anthropics/skills/skills/claude-api
  • Description: Build, debug, and optimize Claude API / Anthropic SDK apps. Includes prompt caching, model migration, and feature configuration.
  • Category: Development
5. doc-coauthoring — Guide users through a structured workflow for co-authoring documentation
  • GitHub: anthropics/skills/skills/doc-coauthoring
  • Description: Guide users through a structured workflow for co-authoring documentation, proposals, technical specs, and decision documents.
  • Category: Writing
6. docx — Read, write, and edit .docx files programmatically
  • GitHub: anthropics/skills/skills/docx
  • Description: Handles .docx files as input or output. Creates formatted Word documents, reports, and templates via python-docx.
  • Category: Document
7. frontend-design — Create distinctive, production-grade frontend interfaces
  • GitHub: anthropics/skills/skills/frontend-design
  • Description: Create distinctive, production-grade frontend interfaces with high design quality. Use when building web components, pages, and applications.
  • Category: Design
8. internal-comms — Write all kinds of internal communications
  • GitHub: anthropics/skills/skills/internal-comms
  • Description: A set of resources to write internal communications using company-specific formats. Includes templates for memos, announcements, and updates.
  • Category: Writing
9. mcp-builder — Guide for creating high-quality MCP servers
  • GitHub: anthropics/skills/skills/mcp-builder
  • Description: Guide for creating high-quality MCP servers that enable LLMs to interact with external services through well-designed tools. Supports Python (FastMCP) and Node/TypeScript (MCP SDK).
  • Category: Development
10. pdf — Extract text and tables from PDFs, fill forms, merge files
  • GitHub: anthropics/skills/skills/pdf
  • Description: Extract PDF text, tables, and forms using pdfplumber. Handles PDF as input or output, including HTML reports and database pipelines.
  • Category: Document
11. pptx — Create and manipulate .pptx slide decks
  • GitHub: anthropics/skills/skills/pptx
  • Description: Use any time a .pptx file is involved — creating slide decks, pitch decks, or presentations. Handles both input and output.
  • Category: Document
12. skill-creator — Create, edit, optimize, and evaluate skills
  • GitHub: anthropics/skills/skills/skill-creator
  • Description: Create new skills, modify existing ones, run evals, benchmark performance with variance analysis, and optimize skill descriptions for better triggering accuracy.
  • Category: Development
13. slack-gif-creator — Create animated GIFs optimized for Slack
  • GitHub: anthropics/skills/skills/slack-gif-creator
  • Description: Knowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts.
  • Category: Design
14. theme-factory — Style artifacts with pre-set themes
  • GitHub: anthropics/skills/skills/theme-factory
  • Description: Toolkit for styling artifacts with 10 pre-set themes. Works with slides, docs, reports, HTML landing pages, and more.
  • Category: Design
15. web-artifacts-builder — Build and deploy web artifacts
16. webapp-testing — Toolkit for interacting with and testing local web applications
  • GitHub: anthropics/skills/skills/webapp-testing
  • Description: Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing screenshots, and viewing browser logs.
  • Category: Testing
17. xlsx — Read, write, and edit .xlsx spreadsheets
  • GitHub: anthropics/skills/skills/xlsx
  • Description: Handles .xlsx files as input or output. Creates formatted spreadsheets, data reports, database pipelines, and Google Sheets API integrations.
  • Category: Document

Community Skills

18. caveman — Agent-centric workflow orchestration by Julius Brussee
  • GitHub: JuliusBrussee/caveman
  • Description: Caveman is a workflow orchestration framework for AI agents. It defines a declarative YAML format for agent workflows with sequential, parallel, and conditional execution steps. Skills in caveman focus on structured agent behavior, repeatable task patterns, and multi-step orchestration.
  • Category: Development / Workflow Orchestration
  • Installation:
git clone https://github.com/JuliusBrussee/caveman.git

Place desired patterns in .agents/skills/
19. spec-kit — Specification-driven development tools by GitHub
  • GitHub: github/spec-kit
  • Description: Spec-kit provides tools and skills for specification-driven development. It enables agents to work from formal specifications, generate code from specs, and validate implementations against requirements. Particularly useful for contract-first development and API design workflows.
  • Category: Development / Specification-Driven
  • Installation:
git clone https://github.com/github/spec-kit.git

Install specs and skills into your agent's skill directories
20. agency-agents — Multi-agent orchestration framework
  • GitHub: msitarzewski/agency-agents
  • Description: Agency-agents is a framework for orchestrating multiple AI agents with defined roles, communication patterns, and task delegation. Skills in this framework define agent roles, handoff protocols, and coordination patterns for complex multi-agent workflows.
  • Category: Development / Multi-Agent Orchestration
  • Installation:
git clone https://github.com/msitarzewski/agency-agents.git

Reference the agent patterns and role definitions

How to Install & Use Skills

Skills are portable across all compatible agents. The installation process is the same whether you use VS Code, Claude Code, OpenCode, or any other skill-supporting tool.

Method 1: Manual Installation (Works Everywhere)

# 1. Create the skills directory in your project
mkdir -p .agents/skills/


2. Clone the skill you want

git clone https://github.com/anthropics/skills.git /tmp/skills


3. Copy the skill into your project

cp -r /tmp/skills/skills/pdf .agents/skills/


4. (Optional) Remove the clone

rm -rf /tmp/skills

Method 2: Quick Install with npx

Some skills can be installed directly: 

npx -y @anthropic/skills install pdf

Method 3: Clone Full Repository

git clone https://github.com/anthropics/skills.git

Then copy individual skills as needed

Default Skill Directories

Agents scan these directories for skills:

Agent Default Directory
VS Code + Copilot .agents/skills/
Claude Code .claude/skills/ or .agents/skills/
OpenCode .agents/skills/
Gemini CLI .agents/skills/
OpenClaw .openclaw/workspace/skills/
Junie .agents/skills/

Using Skills

Once installed:

  1. Restart your agent or reload the session
  2. Ask a question related to the skill — e.g., "Extract text from this PDF"
  3. The agent automatically detects the matching skill and loads its instructions
  4. The agent follows the skill's steps to complete your task

To list installed skills, ask your agent:

Creating Your Own Skill

Creating a skill is straightforward — one file under 20 lines.

Quickstart: Roll Dice Skill

Create .agents/skills/roll-dice/SKILL.md:

---
name: roll-dice
description: Roll dice using a random number generator. Use when asked
  to roll a die (d6, d20, etc.) or generate a random dice roll.




To roll a die, use the following command:


Bash:
bash echo $((RANDOM % + 1)) 

PowerShell:
powershell Get-Random -Minimum 1 -Maximum ( + 1) 

Replace  with the number of sides on the die.

Then in VS Code Copilot Chat Agent mode, ask "Roll a d20" — the agent activates the skill and runs the command.

Progressive Disclosure

When an agent starts, it reads only the name and description of each skill. The full SKILL.md body is loaded only when the skill is activated by a matching query. This allows agents to carry hundreds of skills without context window bloat.

Best Practices

Practice Description
Start from real expertise Base skills on real task execution, not generic instructions
Refine with real execution Run the skill, then iterate based on results
Spend context wisely Add what the agent lacks, omit what it already knows
Well-scoped descriptions Include specific keywords for accurate activation
Use progressive disclosure Keep SKILL.md focused; use scripts/ for dense code
Test and evaluate Run evals to measure skill performance and activation accuracy
Version your skills Use metadata.version field for tracking changes

Description Optimization Tips

Write descriptions that help the agent decide when to activate:

  • Include both what the skill does AND when to use it
  • Add specific keywords that trigger on relevant prompts
  • Avoid vague descriptions like "Helps with PDFs" — be specific

Good: "Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction." Poor: "Helps with PDFs."

Which Tools Support Skills

The following tools support the Agent Skills format (Source: agentskills.io):

Tool Support Skills Config
GitHub Copilot (VS Code) Full .agents/skills/
Claude Code Full .claude/skills/ or .agents/skills/
OpenCode Full .agents/skills/
Gemini CLI Full .agents/skills/
OpenHands Full .agents/skills/
Junie (JetBrains) Full .agents/skills/
Autohand Code CLI Full .agents/skills/
OpenClaw Full Via skills.sh / ClawHub
Mux Full .agents/skills/