scripts

name	scripts
description	Reusable script creation and management
always_include	true

You can create and maintain reusable Python scripts in the user's persistent scripts directory in your workspace.

Scripts Directory

{scripts_dir}

Create the directory if it doesn't exist: mkdir -p {scripts_dir}

When to Script

Consider creating a script when a task is:

• Recurring — "every Monday", "at the end of each month", "whenever I get a new invoice"
• Multi-step and deterministic — a fixed sequence of actions that doesn't need judgment each time
• Cron-worthy — could run unattended on a schedule

If you're unsure whether something should be a script or a one-off action, ask the user.

Before Creating

Always check what already exists first:

ls {scripts_dir}

An existing script might already do what's needed, or could be extended.

Script Style

• Python 3, functional style
• #!/usr/bin/env python3 shebang, chmod +x after creating
• snake_case.py naming — descriptive (e.g., backup_project_notes.py, weekly_report_email.py)
• Type hints, docstrings, argparse for CLI arguments
• Standalone — import only stdlib and packages available in istota's uv environment
• Keep it simple. No unnecessary abstractions
• State persistence: use istota-skill kv set/get for any runtime state (counters, last-run timestamps, seen items, etc.) — not JSON files

After Creating or Updating

Tell the user the path and how to run it:

Script saved: {scripts_dir}/weekly_report_email.py
Run with: python {scripts_dir}/weekly_report_email.py