Authoring Guide

Overview

A toolkit is a directory with tool definitions, metadata, and dependencies. You write tools as Python functions decorated with @define_tool (from Orchestral AI), describe the toolkit in toolkit.yaml, and publish.

1. Create a toolkit

Scaffold a new toolkit:

scitoolkit init my-toolkit
cd my-toolkit

You'll get a working template:

my-toolkit/
├── toolkit.yaml          # Metadata
├── tools/                # Your tool definitions
│   ├── __init__.py       # Exports tools (this matters!)
│   └── example.py        # Sample tool to start from
├── skills/               # Optional: markdown guides for agents
├── requirements.txt      # Python dependencies
├── README.md             # Documentation (rendered on the website)
└── setup.py              # Optional: custom setup logic

2. Define tools

Tools are Python functions. Use the @define_tool decorator and return a JSON string:

# tools/transit.py
from orchestral import define_tool
import json

@define_tool
def calculate_transit_depth(planet_radius: float, star_radius: float) -> str:
    """
    Calculate the transit depth of an exoplanet.

    Args:
        planet_radius: Planet radius in Earth radii
        star_radius: Star radius in solar radii
    """
    depth = (planet_radius / (star_radius * 109.1)) ** 2
    return json.dumps({"transit_depth_ppm": depth * 1e6})

Type hints and docstrings are required — they become the schema shown to the AI agent. If the agent doesn't know what an argument means, it can't use the tool correctly.

3. Export your tools

List your tools in tools/__init__.py. SciToolkit reads this to discover what to serve:

# tools/__init__.py
from .transit import calculate_transit_depth

__all__ = ["calculate_transit_depth"]

Tools not in __all__ will not be exposed to agents. This lets you have helper functions in tools/ without exposing them.

4. Fill in toolkit.yaml

name: my-toolkit
version: 1.0.0
category: astro
description: "Brief description of what your toolkit does"
author: "Your Name"
license: "MIT"
homepage: "https://github.com/you/my-toolkit"
keywords:
  - exoplanets
  - astrophysics

If your toolkit needs a specific Python version, declare it. This is how SciToolkit decides whether to use venv, conda, or Docker:

environment:
  python: "3.12"             # Default: current Python version
  type: auto                 # auto, venv, conda, docker
  docker_required: false     # Force Docker mode

See Configuration & Setup if your toolkit needs API keys, file paths, or custom setup.

5. Categories

Pick the category that best describes your toolkit. This affects how it's shown on the registry:

6. Validate your toolkit

Before publishing, run the validator to catch structural problems:

scitoolkit validate

This checks that toolkit.yaml is well-formed, your tools have type hints and docstrings, and your tools/__init__.py properly exports them. It also flags common anti-patterns.

7. Authenticate the CLI

Run scitoolkit login and follow the browser prompt:

scitoolkit login

Sign in once, and the CLI is authenticated for any toolkit you own or collaborate on. No need to repeat for new toolkits.

Need a non-interactive flow (CI, agents)? Generate a token at CLI Tokens and pass it with scitoolkit login --token <token>. Full details on the Authentication page.

Per-toolkit publish tokens (legacy scitoolkit login <toolkit>) still work but are being phased out. Migrate to a per-user token at your earliest convenience.

8. Publish

scitoolkit publish

The CLI packages your toolkit into a tarball, uploads it, and registers the version. The version comes from toolkit.yaml.

Updating

To publish a new version: bump the version in toolkit.yaml (semantic versioning, X.Y.Z) and run scitoolkit publish again. Each published version is preserved — users can pin to specific versions, and the latest version is what scitoolkit install <name> fetches by default.

Versions cannot be re-uploaded. If you need to fix a broken version, publish a new one with the next patch number.

Skills (optional)

Skills are markdown files in a skills/ directory that teach an AI agent how to use your tools, not just what tools exist. They're step-by-step guides like:

# Modeling exoplanet transits

## When to use this skill
When the user asks to model a transit lightcurve.

## Steps
1. Use `load_stellar_params` to get the host star.
2. Pass those to `calculate_transit_depth` along with planet params.
3. Plot with `render_lightcurve` and return the path.

Skills are listed in toolkit.yaml and rendered on your toolkit's page. They're also surfaced to agents at serve time.