An agent skill packages instructions, and optionally scripts or supporting documents, for a class of tasks. It addresses a prompt-management problem: as an agent gains tools, keeping every tool definition in every prompt wastes tokens and can make tool selection less accurate. Skills leave detailed instructions in the agent’s workspace and expose only short descriptions until they are needed. section 8.5 section 8.5.1
A skill is disclosed in stages:
- List: put each skill’s name and one-line description in the system prompt so the agent can identify a relevant capability. section 8.5.2
- Instructions: when a skill is relevant, read its SKILL.md for usage, examples, options, and caveats. section 8.5.2
- Execution: read any further documents only if needed, then run the skill’s scripts or write code using its instructions. section 8.5.2
Each skill occupies one folder with a required SKILL.md. Its YAML front matter supplies the name and description shown in the prompt; the rest documents how to use the skill. Scripts can live beside it. Keeping these files together makes a skill portable between agent environments. section 8.5.1
To wire skills into a Python agent, discover skill folders, read each SKILL.md front matter into a SkillInfo containing its name, description, and path, and generate a prompt listing only the summaries. Give the Agent a skills_path and upload those folders when its sandbox starts. The prompt tells the agent where to read a selected skill’s SKILL.md through the CLI. section 8.5.3
Merge PDFs on demand
A pdf-merge skill’s SKILL.md describes merging files with pypdf. For a request to combine three reports, the agent selects the skill from its description, reads SKILL.md with bash_tool, writes and runs the merge code with execute_python, then checks that merged.pdf exists. Unrelated requests do not load the merge instructions. section 8.5.4
Listing 8.33 SKILL.md file for the pdf-merge skill
---
name: pdf-merge
description: Merge multiple PDF files into a single PDF document. Use when the user wants to combine, merge, concatenate, or join PDF files together into one file.
---
# PDF Merge
Merge multiple PDFs into a single document using pypdf.
## Usage
```python
from pypdf import PdfWriter, PdfReader
writer = PdfWriter()
pdf_files = ["file1.pdf", "file2.pdf", "file3.pdf"]
for pdf_file in pdf_files:
reader = PdfReader(pdf_file)
for page in reader.pages:
writer.add_page(page)
with open("merged.pdf", "wb") as output:
writer.write(output)
```
The SKILL.md example shows the boundary between prompt-visible YAML metadata and the detailed Python usage instructions read on demand. section 8.5.4
Skills sit between core tools, whose definitions remain in the prompt, and generated tools, whose code the agent writes as needed. Their benefit is selective context use, not free execution: the agent still needs workspace access and the libraries required by a skill’s instructions. In the PDF example, pypdf is assumed to be present in the sandbox. section 8.6 section 8.5.4
