Publishing Tools

Share tools across projects, organize the powers/ directory, and use recursive discovery.

Tools live in the powers/ directory, and supypowers discovers them automatically. This page covers how to organize tools, share them across projects, and control what gets discovered.

The powers/ Directory

Every supyagent project has a powers/ directory at its root:

my-project/
  agents/
    myagent.yaml
  powers/
    shell.py        # Default tool
    files.py        # Default tool
    edit.py         # Default tool
    search.py       # Default tool
    find.py         # Default tool
    patch.py        # Default tool
    git.py          # Default tool
    plan.py         # Default tool
    web.py          # Default tool
    browser.py      # Default tool (optional)
    weather.py      # Your custom tool
    my_api.py       # Another custom tool

When an agent starts, supyagent runs supypowers docs --format json to discover all functions in powers/. Each .py file is inspected for functions matching the supypower contract (single input parameter typed as BaseModel).

Organizing with Subdirectories

For larger projects, organize tools into subdirectories:

powers/
  core/
    shell.py
    files.py
    edit.py
  integrations/
    slack_tools.py
    github_tools.py
  analytics/
    chart_builder.py
    data_processor.py

To discover tools in subdirectories, use the --recursive flag:

supypowers docs --recursive
supypowers docs --recursive --format md

Without --recursive, only top-level .py files in powers/ are discovered.

Recursive Discovery in Agent Config

When supyagent discovers tools, it uses recursive discovery by default, so tools in subdirectories are automatically available to your agents.

Method 1: Copy the Script

The simplest approach -- just copy the .py file into another project's powers/ directory:

cp ~/project-a/powers/weather.py ~/project-b/powers/

Since each script declares its own dependencies inline, it works immediately in the new project.

Method 2: Symlink

For tools you maintain in a central location:

ln -s ~/my-tools/weather.py powers/weather.py

Method 3: Shared Tools Directory

Point supypowers at a shared directory:

supypowers docs --root /path/to/shared-tools
supypowers run --root /path/to/shared-tools weather:get_weather '{"city": "London"}'

Method 4: Git Submodule

For teams, maintain a shared tools repository:

git submodule add https://github.com/your-org/shared-tools.git powers/shared

With --recursive discovery, all tools in powers/shared/ are available automatically.

Default Tools

When you run supyagent init, a set of default tools are copied into powers/:

Tool	Functions
`shell.py`	`run_command`, `run_script`, `which`, `get_env`
`files.py`	`read_file`, `read_file_lines`, `write_file`, `list_directory`, `file_info`, `delete_file`, `create_directory`, `copy_file`, `move_file`
`edit.py`	`edit_replace`, `insert_lines`, `replace_lines`, `multi_edit`, `regex_replace`
`search.py`	`search`, `count_matches`
`find.py`	`find_files`, `recent_files`, `directory_tree`
`patch.py`	`apply_patch`
`git.py`	`git_status`, `git_diff`, `git_commit`, `git_log`, `git_branch`
`plan.py`	`create_plan`, `update_plan`, `get_plan`
`web.py`	`fetch_url`, `http_request`
`browser.py`	`browse`, `screenshot`, `click`, `type_text`, `get_page_state`, `close_browser`

These are regular supypowers scripts -- you can modify them, remove ones you don't need, or use them as templates.

See the Built-in Tools reference for detailed documentation.

Controlling Tool Access

In your agent config, control which tools an agent can use:

agents/restricted.yaml

tools:
  allow:
    - "weather:*"       # All functions in weather.py
    - "files:read_file" # Only read_file from files.py
    - "search:*"        # All search functions

  deny:
    - "shell:*"         # No shell access
    - "files:delete_file" # No file deletion

Generating Documentation

View all discovered tools and their schemas:

# JSON format (used by supyagent internally)
supypowers docs --format json

# Markdown format (human-readable)
supypowers docs --format md

# Write to a file
supypowers docs --format md --output TOOLS.md

# Include subdirectories
supypowers docs --recursive --format md --output TOOLS.md

The `--require-marker` Flag

For scripts that contain multiple functions but you only want to expose some of them, use the @superpower decorator pattern and the --require-marker flag:

powers/utils.py

def superpower(fn):
    """Marker decorator for supypowers."""
    return fn

@superpower
def public_function(input: MyInput) -> MyOutput:
    """This will be discovered."""
    ...

def internal_helper(input: HelperInput) -> HelperOutput:
    """This will NOT be discovered with --require-marker."""
    ...

supypowers docs --require-marker

Only functions decorated with @superpower will appear in the docs.

What's Next

Creating Tools -- The supypower contract
Examples -- Common tool patterns
Built-in Tools -- Reference for all default tools

On this page