Build Skills That Use Python and Dependencies — The Complete Pattern

Markdown-only skills cover an enormous range of capabilities. For more complex logic, skills bundle scripts. Here is the full pattern for Python skills with dependencies, file processing and error handling.

Once you have built a few markdown-only skills, you will encounter cases where instructions alone are not enough — tasks that need actual computation, file processing, data transformation or API calls. The skill standard handles this elegantly by bundling executable scripts alongside SKILL.md.

The Folder Structure

A Python skill follows a conventional structure:

my-skill/
├── SKILL.md
├── requirements.txt
└── scripts/
    └── main.py

SKILL.md remains the entry point — the agent reads it to know when to use the skill and how. The scripts/ folder holds the Python code. The requirements.txt lists Python dependencies that get installed automatically the first time the skill activates.

The requirements.txt File

The skill specification supports automatic dependency installation. Your requirements.txt is a standard pip requirements file:

pandas>=2.0.0
tabulate>=0.9.0
requests>=2.31.0

When the skill is invoked for the first time, the agent runs pip install -r requirements.txt before executing any scripts. Subsequent invocations skip the install since the packages are already present.

The Main Script Pattern

Here is the conventional pattern for the main script — taking a path argument, processing it, printing structured output:

#!/usr/bin/env python3
# Summarise a CSV file with statistics
import sys
import pandas as pd
from tabulate import tabulate

def summarise(path):
    df = pd.read_csv(path)
    print(f"## Summary of {path}")
    print(f"- Rows: {len(df)}")
    print(f"- Columns: {len(df.columns)}")
    print(tabulate(df.head(), headers="keys", tablefmt="github"))

if __name__ == "__main__":
    summarise(sys.argv[1])

The script reads its arguments from sys.argv (the agent passes the user inputs there). It prints structured output to stdout — the agent captures this output and presents it to the user. Errors should go to stderr so the agent can recognise them and respond appropriately.

The SKILL.md That Connects Everything

The SKILL.md tells the agent how to use the script:

---
name: csv-summariser
description: Reads a CSV file and produces a structured
  statistical summary. Use whenever the user provides a CSV
  file or asks to analyse, summarise or preview tabular data.
---

## Instructions

1. Install dependencies if needed: pip install -r requirements.txt
2. Run: python3 scripts/main.py [path_to_csv]
3. Present the output to the user as a structured report.

Handling Environment Variables and Secrets

Skills that need API keys should never hardcode them. Use environment variables read at runtime — for Claude Code, set them in ~/.claude/.env. The SKILL.md documents which environment variables the skill expects, but never contains the actual values. This makes skills safely shareable and version-controllable.