automation

# Automation Skill

This skill provides 3 tools for creating and managing scheduled automations:
- `check_automations` - List all or inspect a specific automation
- `create_automation` - Create a new scheduled automation
- `manage_automation` - Update, pause, resume, trigger, or delete automations

You should call these tools directly instead of using ExecuteCode tool.

## Before Creating an Automation

**Always confirm with the user before calling `create_automation`.** Automations run autonomously on a schedule, so getting the details right matters. If the user's request is unclear or underspecified, ask to clarify:

- **Schedule** — "Every morning" is ambiguous. Confirm the exact time and days (e.g. "Weekdays at 9 AM in your timezone?").
- **Thread strategy** — If the task involves ongoing analysis or follow-ups, ask whether they want results in a fresh thread each time, a single persistent thread, or the current conversation.
- **Instruction** — The instruction runs without further user input. If the user gives a vague prompt like "check my portfolio", refine it: what tickers? what metrics? what format?
- **Delivery** — If the user hasn't mentioned how they want to receive results, ask if they want delivery (e.g. Slack) or just in-app.

Summarize what you're about to create and get a "yes" before calling the tool.

---

## Tool 1: check_automations

List all automations or inspect a specific one with execution history.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `automation_id` | str | No | Automation ID to inspect. Omit to list all. |

### Examples

```python
# List all automations
check_automations()

# Inspect a specific automation (includes last 5 executions)
check_automations(automation_id="abc-123")
```

---

## Tool 2: create_automation

Create a new scheduled automation.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | str | Yes | Short name for the automation |
| `instruction` | str | Yes | The prompt the agent will execute on each run |
| `schedule` | str | Yes | Cron expression or ISO datetime (see below) |
| `description` | str | No | Optional description |
| `thread` | str | No | `"new"` (default), `"persistent"`, or `"current"` (see Thread Strategy) |
| `delivery` | str | No | Comma-separated delivery methods (e.g. `"slack"`) |

### Thread Strategy

| Mode | Behavior |
|------|----------|
| `"new"` | Fresh thread each run — no conversation history carried over (default) |
| `"persistent"` | Single dedicated thread — all runs share conversation history |
| `"current"` | Pins to the current conversation thread — automation runs continue here |

### Schedule Format

- **Recurring (cron):** Standard 5-field cron expression
  - `0 9 * * 1-5` — weekdays at 9 AM
  - `0 */4 * * *` — every 4 hours
  - `30 8 1 * *` — 1st of each month at 8:30 AM
- **One-time (ISO datetime):**
  - `2026-03-01T10:00:00` — single execution at that time

### Examples

```python
# Daily market briefing on weekdays at 9 AM
create_automation(
    name="Morning Market Brief",
    instruction="Summarize overnight market moves, top gainers/losers, and any news for my watchlist.",
    schedule="0 9 * * 1-5",
)

# One-time earnings reminder
create_automation(
    name="AAPL Earnings Reminder",
    instruction="Analyze AAPL ahead of earnings: recent price action, analyst expectations, key metrics to watch.",
    schedule="2026-04-30T08:00:00",
    description="Pre-earnings analysis for Apple Q2 2026",
)

# Daily report delivered to Slack
create_automation(
    name="Morning Market Brief",
    instruction="Summarize overnight market moves for my watchlist.",
    schedule="0 9 * * 1-5",
    delivery="slack",
)

# Automation with persistent thread (all runs share history)
create_automation(
    name="Weekly Portfolio Review",
    instruction="Review my portfolio performance and update the analysis.",
    schedule="0 9 * * 1",
    thread="persistent",
)

# Automation that continues in the current conversation
create_automation(
    name="Hourly Price Check",
    instruction="Check AAPL, MSFT, GOOGL prices and alert if any moved >2%.",
    schedule="0 * * * *",
    thread="current",
)
```

---

## Price-Triggered Automations

In addition to cron/datetime schedules, automations can trigger when a stock price meets a specific condition. Set `trigger_type="price"` and provide a `trigger_config` dict instead of (or alongside) a `schedule`.

### Condition Types

| Condition | Description |
|-----------|-------------|
| `price_above` | Fires when price rises above the given value |
| `price_below` | Fires when price drops below the given value |
| `pct_change_above` | Fires when percentage change exceeds the given value |
| `pct_change_below` | Fires when percentage change drops below the given (negative) value |

For percentage conditions, `reference` sets the baseline price:

| Reference | Description |
|-----------|-------------|
| `previous_close` | Prior trading day's closing price (default) |
| `day_open` | Current trading day's opening price |

### Retrigger Modes

| Mode | Behavior |
|------|----------|
| `one_shot` | Trigger once, then mark completed (default) |
| `recurring` | Re-arm after cooldown. Omit `cooldown_seconds` for once-per-trading-day default, or set `cooldown_seconds` (min 14400 = 4 hours) for custom interval. |

### Examples

```python
# Alert when AAPL drops below $150 (one-shot)
create_automation(
    name="AAPL Price Alert",
    instruction="AAPL has dropped below $150. Summarize recent news and analyst sentiment.",
    trigger_type="price",
    trigger_config={
        "symbol": "AAPL",
        "conditions": [{"type": "price_below", "value": 150}],
    },
)

# Run analysis when TSLA moves up 5% from yesterday's close
create_automation(
    name="TSLA Momentum Alert",
    instruction="TSLA is up 5% from yesterday's close. Analyze volume, technicals, and any catalysts.",
    trigger_type=