How to Write and Implement Agent Skills

• Agent Skills are folders that contain a SKILL.md file with metadata and instructions that allow LLMs to load specialized capabilities only when relevant, rather than requiring all context in every prompt. Claude introduced this framework in 2025, and it enables more efficient agent workflows by separating resources into independently accessible modules.

• For agents to use skills, they need to be able to discover, load, and execute them. This involves parsing through available skills and finding the best one for a user’s request.

• Agent skills are likely to become an important standard for adding capabilities to agents. They offer a lot of customization and dynamic potential for agents.

The simplest implementation of a skill is a folder that contains a SKILL.md file. This markdown file includes metadata and instructions for the agent that explain how to perform specific tasks. You can also include additional resources, templates, scripts, and reference materials in the folder.

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

The Skill folder name will be the name of the Skill. Then inside the folder is the SKILL.md file and any additional materials you would like to include.

First, create a folder called skills. This folder will contain all of the Skills that you write. Within the skills folder, create another folder called pdf-parsing. This folder will contain all of the files and documentation for your pdf-parsing Skill. Inside the pdf-parsing folder, create a SKILL.md file with the following content.

---
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

Alternatively, you can call the script directly from the command line:
command
python skills/pdf-parsing/parse_pdf.py extract_text --file_path /path/to/file.pdf --pages all

The name and description are required at the top of the markdown file in the frontmatter for the agent to parse out the descriptions. Frontmatter is the section at the top of the markdown file that contains the metadata. The agent will use these fields from each Skill to identify which Skill is best for a request. You can include optional fields in the frontmatter including license, compatibility, metadata, and allowed-tools. For custom agent workflows, you can add any fields you’d like. The agent will include the frontmatter from each skill with the user’s request to identify which Skill is appropriate.

For the rest of the markdown’s body, there are no specific requirements for the instructions. Try to follow prompting best practices and keep the instructions clear for the LLM to follow. The rest of the body will be queried after the agent has determined which Skill to use.

Then either use this free PDF parser script or create a parse_pdf.py file with an extract_text() function with the PDF parsing functionality. Make sure you install any dependencies each time you add a Skill. For the linked script, you will need PyPDF2.

pip3 install PyPDF2

This will install the PyPDF2 Python package.

For Skills to be used by an agent, the agent needs to follow certain steps. It needs to discover Skills in all directories with the SKILL.md file, load the metadata (name and description) of each markdown file at startup, match the user’s request to relevant Skills, activate the Skills by loading the full instructions from the markdown file, and execute the skill by loading referenced files, following instructions, and running code as needed.

Some agents, like Claude Code and Codex, automatically integrate the Skills into their workflows, and a growing number of agent providers are integrating these steps into their agents’ workflows.

If you want to integrate your skill into your own custom agent, there are two main ways to do so. You can either use a filesystem-based pattern or a tool-based pattern. With a filesystem-based pattern, the LLM workflow operates within a computer environment and outputs shell commands such as cat /path/to/my-skill/skill.md that are then executed. Alternatively, the tool-based approach effectively turns the Skills into tools that the LLM can call.

Building a Skill-enabled agent from scratch is out of scope for this tutorial, but you can use this agent script. The script uses Llama 3.3 70B through the DigitalOcean Gradient AI Platform’s Serverless Inference tool. You will need to get a model access key to use Serverless Inference on the DigitalOcean Gradient AI Platform. Add your model access key in the main() function of the script.

Once you have the script in the same folder as your skills folder, run the script.

python3 agent_example.py

In the text box that it opens for you, enter: Please parse the text out of the PDF at /path/to/your/document.pdf. You should see an output with the parsed 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 found the Skill, extracted the meta data, executed the Skill, and returned the text from the PDF.

Add any other scripts or folders that you would like the LLM to have access to. Then add instructions and descriptions of the functionality for each folder and script in the SKILL.md file. For instance, you may add scripts that can generate or edit PDFs. Ensure you add these additional files in the folder of the specific skill you want them to be associated with.

It’s possible to add as many Skills as you’d like, but each Skill folder must have a SKILL.md file in the folder for it to be recognized by the agent. Furthermore, it can be difficult for an agent to match a user’s intent to the metadata of many Skills, so as the number of Skills increases, it may be necessary to add additional search functionality or use vector embeddings to match a user request to the correct skill.

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 recognize when multiple Skills may be needed and chain them together. It’s possible to reference other Skills in the skill instructions also.

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

Never hardcode credentials in skill files. Use environment variables or a secure secrets manager.

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

Loading the metadata for hundreds of Skills can be slow. Consider caching loaded Skills and using indexing for faster searching across many Skills. You can separate the discovery and activation steps to only load the metadata until the full skill is required.

How do I test and debug Skills?

Make sure you test individual Skills before integrating them, and add verbose logging to your Skills to see which Skills are being selected and why.

Agent Skills are an excellent way to standardize an LLM agent’s functionality. They allow users to add and improve agent capabilities in a structured way. How you implement them depends on your specific agent workflow, but the number of agent services that can use Skills out-of-the-box is increasing, with Claude Code, Codex, and VSCode being just a few of the agent providers that have adopted this standard.

Next, add more Skills and customize them with additional functionality that is appropriate for your project. Then, improve the skill matching capabilities of your agent workflow through vector embeddings or other searching functionality.

• How to Run Open-Weight Nemotron 3 Models on a GPU Droplet
• How to Build Parallel Agentic Workflows with Python
• Mistral 3 Models on DigitalOcean