List files in a directory

List directory entries with type and size as JSON from a system-info skill script.

list_directory.py

#!/usr/bin/env python3
"""List files in a directory."""

import json
import os
import sys

# ---------------------------------------------------------------------------
# Create Example
# ---------------------------------------------------------------------------

if len(sys.argv) < 2:
    path = "."
else:
    path = sys.argv[1]

try:
    entries = []
    for entry in os.listdir(path):
        full_path = os.path.join(path, entry)
        entries.append(
            {
                "name": entry,
                "is_dir": os.path.isdir(full_path),
                "size": os.path.getsize(full_path)
                if os.path.isfile(full_path)
                else None,
            }
        )

    result = {
        "path": os.path.abspath(path),
        "count": len(entries),
        "entries": sorted(entries, key=lambda x: (not x["is_dir"], x["name"])),
    }
    print(json.dumps(result, indent=2))
except Exception as e:
    print(json.dumps({"error": str(e)}))
    sys.exit(1)

# ---------------------------------------------------------------------------
# Run Example
# ---------------------------------------------------------------------------

if __name__ == "__main__":
    raise SystemExit("This module is intended to be imported.")

Run the Example

1. Set up your virtual environment

   Mac

   uv venv --python 3.12
   source .venv/bin/activate
   

   uv venv --python 3.12
   .venv\Scripts\activate
   
2. Use the helper

   The system-info skill executes this helper as a subprocess and passes the directory path as its first argument.

Full source: cookbook/05_agent_os/23_skills/sample_skills/system-info/scripts/list_directory.py