Creating Effective File-Based Skills

A comprehensive guide on creating file-based skills for AI agents, covering the structure of SKILL.md and best practices for writing custom scripts.

Posted on: 2026-03-04 by AI Assistant

When building AI agents, expanding their capabilities through specialized “skills” is a common and powerful pattern. While programmatic skills offer dynamic resources and dependency injection, file-based skills provide a clean, standardized, and easily shareable way to equip agents with new tools.

Based on the patterns established in Pydantic AI Skills, let’s explore the fundamental structure and best practices for creating effective file-based skills.

The Basic Skill Structure

Every file-based skill resides in its own directory and requires, at a minimum, a SKILL.md file. A typical structure looks like this:

my-skill/
├── SKILL.md
└── scripts/
    └── process_data.py

The SKILL.md File

The SKILL.md file is the heart of the skill. It tells the agent what the skill does and how to use it. It consists of two main parts:

1. YAML Frontmatter: Contains metadata like name and description.
   • name: A unique identifier using lowercase and hyphens (e.g., arxiv-search). It must be under 64 characters.
   • description: A brief, clear summary of the skill’s purpose (under 1024 characters).
2. Markdown Content: The actual instructions for the agent.

Best Practices for Instructions

• Do: Use clear, action-oriented language, provide specific examples of how to invoke the tools, and clearly define when the agent should use the skill.
• Don’t: Write vague instructions, assume implicit context, or include sensitive data like API keys directly in the instructions.

Adding Custom Scripts

Often, a skill needs to perform custom operations that go beyond standard agent tools (like interacting with a specific API or processing complex data). This is where custom scripts come in.

Scripts should ideally be placed in a scripts/ subdirectory within the skill folder.

Writing Robust Scripts

Scripts act as the executable backend for your skill. They are invoked by the agent (e.g., via a run_skill_script tool) and execute locally. Here are the core rules for writing them:

• Command-Line Arguments: Accept inputs via sys.argv or an argument parser like argparse.
• Output: Print results directly to stdout. JSON format is highly recommended as it is easily parsed by the agent.
• Exit Codes: Always exit with code 0 on success, and a non-zero code on error.
• Error Handling: Catch exceptions gracefully and print error messages to stderr.

Argument Handling

When an agent calls your script, arguments are typically passed as command-line flags. For example:

# Agent calls:
run_skill_script(skill_name='data-analyzer', script_name='analyze', args={'limit': '100', 'format': 'json'})

# Resulting script execution:
# python analyze.py --limit 100 --format json

Your script needs to be prepared to parse these flags correctly.

Output Formatting

While plain text or CSV outputs are possible, JSON Output is the gold standard. Returning a structured JSON object allows the agent to reliably extract the data it needs.

import json

result = {
    "success": True,
    "data": [{"id": 1, "value": 100}],
    "metadata": {"timestamp": "2026-03-03"}
}

print(json.dumps(result, indent=2))

Error Handling

Communicate errors clearly. If a script fails, print a structured error message to stderr and exit with a non-zero status code. This allows the agent to understand why the skill failed (e.g., validation error vs. timeout) and adjust its strategy accordingly.

Conclusion

By adhering to this file-based skill pattern—structuring your SKILL.md clearly and writing robust, well-documented scripts with structured outputs—you can easily scale the capabilities of your AI agents in a maintainable and standardized way.