cape.agent.skills.usertools: Discover and run repo scripts

This module defines the built-in agent skill "user-tools", which teaches the CAPE agent how to use customized scripts the user has placed in the tools/ folder of the repo in which the agent is launched.

Many CAPE-based repos accumulate local scripts that extend CAPE’s built-in capabilities, e.g. scripts to restart failed adaptations or gather surface data. Such scripts are ordinary Python files with an if __name__ == "__main__": block, usually with a help message available from -h or --help.

The skill provides two tools:

• discover_user_tools(): scan the tools folder for executable scripts (those with a __main__ guard) and extract a one-line description from each script’s docstring

• run_user_tool(): run one of the discovered scripts with user-provided command-line arguments

Scripts are run using the same Python executable as the agent itself, so they import the same CAPE installation, and with the repo root as the working folder so relative file names (e.g. "pyFun.json") resolve as they would if the user ran the script from the repo root.

cape.agent.skills.usertools.discover_user_tools(refresh: bool | None = False) → dict

Discover executable scripts in the repo’s tools folder

Scans <ROOT_DIR>/<TOOL_DIR_NAME>/ for Python scripts (top-level only; subfolders are not scanned) containing an if __name__ == "__main__": block. Files whose name starts with an underscore (including __init__.py) are skipped. Results are cached for the rest of the agent session unless refresh is true.

Call:

>>> result = discover_user_tools(refresh=False)

Inputs:

refresh: True | {False} | None

Rescan even if tools were already discovered

Outputs:

result: dict

Keys include success, tooldir, and tools: a list of dicts with name, file, and description for each discovered script

Versions:

• 2026-09-02 @ddalle: v1.0

cape.agent.skills.usertools.run_user_tool(name: str, argv: list | None = None, timeout: int | None = None) → dict

Run a script from the repo’s tools folder

The script must have been discovered by discover_user_tools() (discovery runs automatically if it has not been). The script’s __main__ guard is re-validated before running. The script is executed with the same Python executable as the CAPE agent and with the repo root folder as the working directory.

Call:

>>> result = run_user_tool(name, argv=None, timeout=None)

Inputs:

name: str

Name of a discovered script, with or without ".py"

argv: {None} | list

Command-line arguments to the script, e.g. ["-I", "1:5", "--force"]; use ["--help"] to show the script’s own help message

timeout: {None} | int

Maximum seconds to wait for the script

Outputs:

result: dict

Keys include success (True only if return code is 0), returncode, stdout, and argv

Versions:

• 2026-09-02 @ddalle: v1.0