Getting started

Skills are reusable packages of specialized knowledge and workflows that extend your AI agent's capabilities. They allow you to bundle domain expertise, scripts, templates, and resources that your agent can discover and use when relevant.

What are Skills?

Skills are structured directories containing:

• A SKILL.md manifest file with metadata and instructions
• Optional helper scripts (Python, JavaScript, etc.)
• Optional reference materials and templates
• Optional runtime dependencies

When your agent receives a request that matches a Skill's purpose, it automatically reads the Skill's instructions and follows the defined workflow.

How Skills Work

Skills follow a progressive disclosure model:

1. Level 1 - Discovery: Only the Skill's name and description are loaded into the system prompt (~100 tokens per Skill)
2. Level 2 - Instructions: When triggered, the agent reads SKILL.md to understand the workflow
3. Level 3 - Resources: The agent accesses additional files (scripts, templates, references) only when needed

This approach keeps context usage minimal while providing deep expertise when required.

Example Skill Structure

pdf-processing/
├── SKILL.md              # Required: Skill manifest and instructions
├── requirements.txt      # Optional: Python dependencies
├── scripts/
│   ├── extract.py        # Helper scripts
│   └── merge.py
└── reference/
    └── forms.md          # Additional documentation

Getting Started

Key Concepts

Skill Metadata

Every Skill requires a SKILL.md file with YAML frontmatter containing:

• name: A unique identifier (lowercase, hyphens allowed)
• description: A clear explanation of what the Skill does and when to use it

---
name: pdf-processing
description: Extract text and tables from PDF files. Use when working with PDF documents.
---

# PDF Processing

Instructions for using this skill...

Skill Execution

Skills execute in a secure sandbox environment. Your agent can:

• Read Skill files using bash commands
• Execute scripts included in the Skill
• Install and use declared dependencies
• Access resources and templates

Best Practices

• Keep SKILL.md under 500 lines; split complex instructions into separate files
• Bundle deterministic helper scripts rather than having the agent generate code
• Declare dependencies explicitly in requirements.txt or package.json
• Use clear, descriptive names that indicate the Skill's purpose