Top Agent Skills

Agent Skills

Modular capability packages that extend Claude's functionality. Learn how to develop, deploy, and optimize Agent Skills to achieve advanced features like code execution, document processing, and data analysis.

Skill Architecture

Agent Skills Structure

Understand the modular architecture that enables efficient, on-demand specialization through progressive loading

What are Agent Skills?
Modular, reusable knowledge packages that extend Claude's abilities through progressive loading
  • Folder-based architecture with SKILL.md core file
  • Three-level loading system for optimal performance
  • Progressive disclosure minimizes context usage
  • Metadata loaded at startup, instructions on relevance, resources on demand

Three-Level Loading System

Level 1
Metadata Level

Loaded at startup for skill discovery

YAML frontmatter block with name & description

Level 2
Instructions Level

Loaded when Claude deems skill relevant

Main body of SKILL.md with execution instructions

Level 3
Resources/Scripts Level

Loaded only when needed by main instructions

Linked files, guides, code, templates

Level 1: Metadata Level

Loaded at startup for skill discovery. This level is always loaded to ensure yaml frontmatter block with name & description

Folder Structure

my-skill-folder/
├── SKILL.md                  # Required: Core instructions and metadata
├── scripts/                  # Optional: Executable code
│   ├── example_script.py
│   └── another_tool.sh
├── templates/                # Optional: File templates
│   └── report_template.docx
├── REFERENCE.md              # Optional: Additional context
└── other-resources/          # Optional: Data files, examples
    └── sample_data.json
Required Files
  • • SKILL.md - Core instructions and metadata
Optional Folders
  • • scripts/ - Executable code
  • • templates/ - File templates
  • • other-resources/ - Data files

SKILL.md Structure

---
name: "My Custom Skill"
description: "Brief description for Claude to match relevance"
version: "1.0.0"
author: "Your Name"
tags: ["productivity", "automation", "data-processing"]
allowed-tools: [Read, Execute, Write]  # Optional: Permissions
---

# Skill Content

## Overview
Describe what this skill does and when it should be used.

## Prerequisites
List any requirements or dependencies.

## Step-by-step Instructions
Clear, actionable steps for Claude to follow.

## Examples
Include concrete examples for reliability.

## Error Handling
Describe how to handle common errors and limitations.
Required Metadata Fields
  • nameSkill display name
  • descriptionBrief description for matching

Development & Runtime Process

1

Define Expertise

Package your standards into a Skill folder

Identify the specific domain knowledge or workflow you want to codify

2

Configure Sources

Tell the SDK where to find Skills

Set setting_sources in your development environment

3

Startup Discovery

Claude loads only metadata for all installed Skills

Keeps context lean by loading minimal information initially

4

Model-Invoked

Claude autonomously decides to use a Skill

Based on user prompt context and skill metadata matching

5

Dynamic Loading

Full SKILL.md and resources loaded just-in-time

Optimizes performance by loading content only when needed

6

Execution

Claude uses guidance or runs scripts

Performs the task using the skill's instructions and tools

Key Benefits

On-demand Activation

Claude decides when to use a Skill based on context

Composability

Multiple Skills can be combined for sophisticated tasks

Portability

Open standard for cross-platform use

Security

Control which Skills can use which tools

Security Considerations

Only use trusted Skills, as they can include executable scripts. The allowed-tools field in YAML metadata controls which tools a Skill can access.