How to Create and Use Agent Skills

Agent Skills are folders that contain instructions, scripts, and supporting resources that a Large Language Model (LLM) can load when they are useful for completing specialized tasks in a consistent and repeatable way. Claude introduced this open framework in 2025, and since then, more organizations and agent developers have begun adopting it.

Previously, when assigning a task to an LLM, you often had to manually provide the workflow context every time. Agent Skills make it possible to separate supporting resources and extra instructions into folders that the LLM only accesses when it determines that they are relevant.

For example, if you want your LLM to create PowerPoint presentations, you no longer need to paste your organization’s style guides, graphics, and templates into every prompt. Instead, you can place them in a Skill folder, and the LLM can locate and use those resources independently whenever a presentation is requested. You can create many Skills, and LLMs can use them in a way similar to tools.

In this tutorial, you will build an Agent Skill for parsing PDF files, with optional folders for reference documentation and assets.

Key Takeaways

Agent Skills are folders that include a SKILL.md file containing metadata and instructions. This allows LLMs to load specialized capabilities only when needed, instead of requiring all context in every prompt. Claude introduced this framework in 2025, and it supports more efficient agent workflows by organizing resources into independently accessible modules.

For agents to use Skills, they must be able to discover them, load them, and execute them. This means scanning available Skills and selecting the best match for a user’s request.

Agent Skills are likely to become an important standard for expanding agent capabilities. They provide strong customization options and allow agents to work more dynamically.

Creating the Skill

The most basic version of a Skill is a folder that contains a SKILL.md file. This markdown file stores metadata and instructions for the agent, explaining how specific tasks should be handled. The same folder can also include additional resources such as templates, scripts, reference documents, and other supporting files.

Folder Structure

your-skill-name/
├── SKILL.md          # Required: instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

The folder name of the Skill becomes the Skill name. Inside that folder, you place the SKILL.md file together with any extra materials you want to include.

First, create a folder named skills. This folder will store all Skills you create. Inside the skills folder, create another folder named pdf-parsing. This folder will hold all files and documentation for the pdf-parsing Skill. Then create a SKILL.md file inside the pdf-parsing folder with the following content.

SKILLS.md

---
name: pdf-processing
description: Extracts text from PDF files using PyPDF2.
---

# PDF Processing Skill

## When to use this skill
Use this skill when a user needs to extract text from a PDF file.

## How to Use this Skill
This skill provides the `extract_text()` function from the `parse_pdf.py` script. Import it into your agent script:

python
from skills.pdf_parsing.parse_pdf import extract_text

result = extract_text(
    file_path="/path/to/document.pdf",
    pages="all"  # or "1-3" or "1,2,3"
)

### Parameters
- `file_path` (str): Path to the PDF file
- `pages` (str): Pages to extract - "all", "1-3" (range), or "1,2,3" (specific pages)

### Returns
JSON object with:
- `success` (bool): Whether extraction succeeded
- `file_path` (str): Path to the processed file
- `total_pages` (int): Total pages in PDF
- `extracted_pages` (int): Number of pages extracted
- `pages` (list): Array of {page: number, text: string} objects

You can also run the script directly from the command line:

python skills/pdf-parsing/parse_pdf.py extract_text --file_path /path/to/file.pdf --pages all

The name and description fields are required at the top of the markdown file inside the frontmatter. Frontmatter is the metadata section at the beginning of the markdown file. The agent uses these values from each Skill to decide which Skill best matches a request. You may also add optional frontmatter fields such as license, compatibility, metadata, and allowed-tools. For custom agent workflows, you can define any additional fields you need. The agent can include the frontmatter from each Skill together with the user request to determine which Skill is suitable.

The rest of the markdown file does not have strict formatting requirements. However, it is best to follow strong prompting practices and write instructions that are easy for the LLM to understand. The body of the markdown file is loaded after the agent has selected the Skill it should use.

Next, either use a free PDF parser script or create a parse_pdf.py file that includes an extract_text() function with PDF parsing functionality. Make sure to install all required dependencies whenever you add a Skill. For this script, PyPDF2 is required.

$ pip3 install PyPDF2

This installs the PyPDF2 Python package.

Integrating the Skill

For an agent to work with Skills, it has to recognize and apply them through a defined workflow. First, it scans the available directories for SKILL.md files and reads the basic metadata, including the Skill name and description, during startup. It then compares the user’s request with the available Skills, selects the relevant one, loads the full instructions from the markdown file, and follows those instructions. If required, the agent also loads supporting files or runs code.

Some agent systems already handle this Skill workflow automatically, and more providers are adding similar capabilities to their platforms.

There are two typical ways to make Skills available in a custom agent. One option is a filesystem-based setup, where the model operates in an environment that can execute shell commands, for example reading a Skill file with cat /path/to/my-skill/skill.md. The other option is a tool-based setup, where each Skill is exposed as something the model can call like a tool.

Creating a Skill-enabled agent entirely from scratch is not covered here, but an example script can be used as a starting point. This script connects to a large language model through a serverless inference service. To use it, create an access key for the selected inference platform and insert that key into the script’s main() function.

Place the script in the same directory as your skills folder, then run it.

$ python3 agent_example.py

In the text box that opens, enter: Please parse the text out of the PDF at /path/to/your/document.pdf. You should then receive output containing the extracted text from the PDF.

Output

============================================================
SIMPLE TOOL-BASED SKILLS EXAMPLE
============================================================

✅ Found 1 skills:
   - pdf-processing: Extracts text from PDF files using PyPDF2.

============================================================
CHAT (type 'quit' to exit)
============================================================

You: Please extract the text from: /Desktop/document.pdf

[Turn 1]
💭 LLM: {"function_call": {"name": "activate_skill", "arguments": {"skill_name": "pdf-processing"}}}
..........
The cost of an RV is 30,000

The agent has successfully detected the Skill, read the metadata, executed the Skill, and returned the extracted PDF text.

Adding Functionality and Skills

You can add any other scripts or folders that you want the LLM to access. Then describe the functionality of each folder and script inside the SKILL.md file with clear instructions and descriptions. For example, you might add scripts for creating or editing PDF files. Make sure these extra files are stored inside the folder of the specific Skill they belong to.

You can create as many Skills as needed, but every Skill folder must contain a SKILL.md file so the agent can recognize it. However, when many Skills exist, it can become harder for the agent to match the user’s intent with the metadata. As the number of Skills grows, you may need additional search capabilities or vector embeddings to match user requests with the correct Skill more reliably.

FAQ

Can Skills communicate with each other or call other Skills, and how would you implement skill chaining?

Yes, Skills can call other Skills. The agent should be able to detect when several Skills are required and connect them in a chain. Other Skills can also be referenced directly in the Skill instructions.

How do I handle authentication and API keys within Skills when they need to access external services?

Never store credentials directly in Skill files. Use environment variables or a secure secrets manager instead.

What are the performance implications of loading many Skills at startup, and are there lazy-loading strategies available?

Loading metadata for hundreds of Skills can take time. To improve performance, consider caching loaded Skills and using indexing to search through large Skill collections more quickly. You can also separate discovery from activation, so only metadata is loaded at first and the full Skill instructions are loaded only when needed.

How do I test and debug Skills?

Test each Skill individually before integrating it into the agent. Add detailed logging so you can see which Skills are selected and why.

Conclusion

Agent Skills are a strong way to standardize the functionality of an LLM agent. They make it possible to add and improve agent capabilities in a structured format. The exact implementation depends on your agent workflow, but more agent services are beginning to support Skills directly.

Next, create additional Skills and adapt them with functionality that fits your project. Then improve the Skill-matching capabilities of your agent workflow by using vector embeddings or other search methods.