Executable Code - Agent Skills Advanced Guide

Advanced Techniques

Executable Code in Agent Skills

Leverage the power of deterministic code execution to create production-grade reliable Agent Skills

Why Use Executable Code in Skills?

Determinism & Reliability

Scripts always produce the same output for the same input, unlike variable LLM-generated code

Token Efficiency

Script code never enters context; large scripts or dependencies have zero token cost

Performance

Ideal for heavy computation like parsing large PDFs or running complex algorithms

Real-World Examples from Anthropic

PDF Skill: Python script to extract form fields
Document Skills: Excel, PowerPoint, Word manipulation
Data processing: Complex calculations and transformations

Integrating Executable Code: Structure

Folder Organization

Place scripts in a dedicated folder for clarity

my-skill-folder/
├── SKILL.md                  # Core instructions (references scripts)
├── scripts/                  # Executable code
│   ├── process_data.py
│   ├── validate_input.sh
│   └── utils/
│       └── helper.py
├── REFERENCE.md              # Optional docs
└── resources/                # Templates, data files

Claude uses relative paths like:

python scripts/process_data.py input.csv

Supported Languages

Language capabilities and library support

Python

Primary

Rich libraries via code execution tool

pandasopenpyxlrdkit+2 more

Bash

Supported

Shell commands and utilities

Standard Unix toolsFile operationsSystem utilities

Node.js

Possible

Works if dependencies are minimal

Built-in Node modules only

Advanced Techniques for Scripts

Explicit Instructions in SKILL.md

Guide Claude precisely with clear commands and expected outputs

Example:

First, run `python scripts/extract_fields.py uploaded.pdf` to get form data. Then, parse the JSON output and proceed.

Provide examples of commands and expected outputs
Handle errors with retry instructions
Be specific about file paths and parameters

Input/Output Patterns

Use structured data exchange between Claude and scripts

Arguments

python scripts/analyze.py --file data.csv --mode summary

Stdio

Scripts read from files; output JSON for easy parsing

Best Practice

Scripts should be idempotent, verbose, and return structured data

Error Handling & Robustness

Build resilient scripts with comprehensive error handling

Use try/except blocks in Python
Validate inputs before processing
Use meaningful exit codes
Provide clear error messages
Include validation scripts

Dependencies

Work within the sandboxed environment constraints

Use pre-installed libraries only
No pip installs in sandbox
Design around available packages
Check library availability in Claude Code

Security & Permissions

Secure script execution with proper permissions

Use YAML allowed-tools to restrict access
Audit scripts thoroughly
Only use trusted Skills
Monitor script behavior

Composability

Chain scripts and combine Skills for complex workflows

Chain scripts where one outputs to the next
Combine Skills for different capabilities
Use modular script design
Share data between scripts via files

Progressive Disclosure

Load scripts only when needed for efficiency

Reference scripts conditionally in SKILL.md
Use markdown links for on-demand loading
Organize scripts by functionality
Minimize initial script references

Example: Data Processing Skill

CSV Analyzer

Analyze CSV files with statistics, cleaning, and visualizations

Workflow:

1
Run `python scripts/clean_csv.py input.csv` to clean data
2
Run `python scripts/analyze.py cleaned.csv` for stats (outputs JSON)
3
Parse JSON and summarize insights

scripts/clean_csv.py

import sys
import pandas as pd

# Read CSV
df = pd.read_csv(sys.argv[1])

# Clean data
df = df.dropna()
df = df.drop_duplicates()

# Save cleaned data
df.to_csv('cleaned.csv', index=False)
print(f"Cleaned {len(df)} rows")

scripts/analyze.py

import sys
import pandas as pd
import json

# Read cleaned CSV
df = pd.read_csv(sys.argv[1])

# Calculate statistics
stats = {
    "rows": len(df),
    "columns": len(df.columns),
    "numeric_columns": list(df.select_dtypes(include=['number']).columns),
    "mean": df.mean(numeric_only=True).to_dict(),
    "std": df.std(numeric_only=True).to_dict(),
    "missing_values": df.isnull().sum().to_dict()
}

# Output JSON
print(json.dumps(stats, indent=2))

Code Execution Tool Environment

Sandboxed environment

Python 3.x with pre-installed libraries

Bash shell with Unix tools

File system access within workspace

No network access (security)

Time/memory limits

Development Tips

Test in Separate Sessions

Observe Claude's bash commands to understand execution patterns

Start with skill-creator

Use built-in helper for scaffolding script structure

Check Anthropic's GitHub

Reference document skills scripts like PDF extraction

github.com/anthropics/skills

Iterate Based on Failures

Run tasks without script → identify failures → add script

Production-Grade Reliability

Executable code elevates Skills from guided prompts to hybrid agent-tools, enabling production-grade reliability. For complex needs, combine with multiple modular Skills!