---
name: archagent-build-script
description: Use when the user wants to write, test, or deploy an ArchAstro script — custom logic for agent tools, workflow nodes, and routines. Trigger phrases include "build a script", "write a script", "create a script", "test a script", "script syntax", "script reference", "script language".
allowed-tools: ["Bash(archagent:*)"]
---

# ArchAstro Script Builder

Write, test, and deploy scripts — custom logic that powers agent tools, workflow nodes, and routines.

This skill assumes the ArchAgent CLI is already installed and authenticated. Install or upgrade `archagent` if missing, and run `archagent auth login <email>` if not authenticated.

## What is a Script?

Scripts are expression-oriented custom logic written in the ArchAstro script language. They can be used as:
- **Custom tool handlers**: Agent calls a tool → script runs → result returned to agent
- **Workflow graph script steps**: Script logic used inside a workflow graph
- **Routine handlers**: A scheduled routine runs the script directly

Scripts are first-class resources with their own CRUD, validation, and execution commands.
Use the dedicated top-level script resource for the normal authoring loop: `archagent list scripts`, `describe script`, `create script`, `update script`, `validate script`, `run script`, and `describe scriptdocs`.

## Always Start with State

Every invocation must begin by understanding the current context:

```
archagent auth status
archagent list scripts
```

Determine:
- Is the user creating a new script or editing an existing one?
- What will this script be used for? (tool, workflow node, routine)
- What external APIs or data does it need to access?

## Routing

### User wants to write a new script

**Phase 1: Get the language reference**

Always start by fetching the live reference — do not write scripts from memory:
```
archagent describe scriptdocs
```

Use the top-level script commands, not `describe configsample`/`validate config`, for the normal authoring loop.

Create a script from a local source file:
```
archagent create script --id my-script --file ./scripts/my-script.agentscript
```

Or let the CLI start from its built-in sample if you do not pass `--source` or `--file`:
```
archagent create script --id my-script
```

**Phase 2: Understand the requirements**

Ask the user:
- What should the script do?
- What inputs will it receive? (accessible via `$` JSONPath)
- Does it need environment variables? (accessible via `env.KEY`)
- Does it need to make HTTP calls?

If the script will handle a routine event, discover what `$` contains by checking the event's payload schema:
```
archagent list events
archagent describe event <event-name>
```

`describe event` returns the JSON schema and a sample payload. Every field in the payload is accessible via `$` in the script (e.g., `$.thread_id`, `$.message.content`). Always check the event schema before writing scripts that consume routine payloads — do not guess the shape from memory.

**Phase 3: Author the script**

Key language concepts:

- **Input**: Access via `$` (JSONPath). E.g., `$.order_id`, `$.user.email`
- **Environment**: Access via `env.KEY`. E.g., `env.API_TOKEN`
- **Imports**: `import("requests")`, `import("array")`, `import("string")`, etc.
- **Error handling**: `unwrap(result)` or `unwrap(result, default_value)`
- **No loops**: Use `array.map`, `array.filter`, `array.reduce`
- **Expression-oriented**: The last expression in the script is the return value
- **Debugging**: Use `println()` to inspect values

Example — HTTP lookup script:
```
let http = import("requests")
let arr = import("array")

let response = http.get(env.API_URL + "/orders/" + $.order_id, {
  headers: { "Authorization": "Bearer " + env.API_TOKEN }
})
let body = unwrap(response)

{
  order_id: $.order_id,
  status: body.status,
  items: arr.map(body.line_items, fn(item) {
    { name: item.name, qty: item.quantity }
  })
}
```

Available namespaces:
- `requests` — HTTP client (`get`, `post`, `put`, `patch`, `delete`)
- `array` — Collection operations (`map`, `filter`, `reduce`, `find`, `sort`, `flat_map`)
- `string` — String operations (`split`, `join`, `trim`, `lowercase`, `uppercase`, `contains`)
- `map` — Object operations (`keys`, `values`, `merge`, `get`)
- `datetime` — Date/time operations (`now`, `format`, `parse`, `add`)
- `math` — Math operations (`round`, `floor`, `ceil`, `abs`)
- `result` — Result type operations (`ok`, `err`, `is_ok`, `is_err`)
- `email` — Email sending
- `jwt` — JWT token operations
- `slack` — Slack API operations

**Phase 4: Validate**

Validate the script syntax:
```
archagent validate script --file ./scripts/my-script.agentscript
```

Or validate as a config:
```
archagent validate config -k Script -f ./configs/scripts/my-script.yaml
```

Fix any validation errors before proceeding.

**Phase 5: Test**

Run the script locally with test input:
```
archagent run script --file ./scripts/my-script.agentscript --input '{"order_id": "ORD-123"}'
```

For scripts that need env vars, ensure they are set on the platform:
```
archagent list orgenvvars
archagent create orgenvvar -k API_TOKEN -v "sk-..."
```

**Phase 6: Deploy**

Scripts can be deployed two ways:

**As a standalone script resource:**
```
archagent create script --id order-lookup -n "Order Lookup" --file ./scripts/my-script.agentscript
```

Update an existing script resource:
```
archagent update script order-lookup --file ./scripts/my-script.agentscript
```

**Via `deploy configs`** (for config-managed repos):

Place `.agentscript` files in `configs/scripts/` and deploy:
```
archagent deploy configs
```

The `scripts/` directory enforces that only `.agentscript` files and `.yaml`/`.json` with `kind: Script` are allowed — other file types are rejected. See the `manage-configs` skill for setting up the configs directory.

**Phase 7: Wire it up**

Connect the script to where it will be used:

**As a custom tool on an agent:**

The API requires `--config-id` pointing at the script's config ID even for script-handler tools:
```
archagent create agenttool --agent <agent-id> \
  --kind custom \
  --name "lookup_order" \
  --description "Look up an order by ID" \
  --handler-type script \
  --config-id <script-config-id> \
  --instruction "Use this tool when the user asks to look up an order." \
  --parameters '{"type":"object","properties":{"order_id":{"type":"string"}},"required":["order_id"]}'
```

Get the script's config ID from `archagent describe script <id> --output json` (the `configId` field).

**In a workflow graph:** Follow the real `WorkflowGraph` shape from `archagent describe workflowdocs` and the `build-workflow` skill.

**As a routine handler** (reference by config ID — preferred for production):
```
archagent create agentroutine --agent <agent-id> \
  --name "My scheduled script" \
  --event-type schedule.cron \
  --schedule "0 9 * * 1-5" \
  --handler-type script \
  --config-id <script-config-id>
```

Get the script's config ID from `archagent describe script <id> --output json` (the `configId` field).

Or inline for quick prototyping:
```
archagent create agentroutine --agent <agent-id> \
  --name "Quick test" \
  --event-type schedule.cron \
  --schedule "0 9 * * 1-5" \
  --handler-type script \
  --script 'println("hello")'
```

Prefer `--config-id` for production — it keeps the routine linked to a versioned script resource that can be updated independently.

### User wants to edit an existing script

1. **Inspect the current script**:
   ```
   archagent list scripts
   archagent describe script <id>
   ```

2. **Edit locally**, validate, and update:
   ```
   archagent validate script --file ./scripts/my-script.agentscript
   archagent update script <id> --file ./scripts/my-script.agentscript
   ```

## Common Mistakes

**Do not write JSON — use script object syntax:**
```
// WRONG — JSON syntax causes "unexpected token :" errors
{ "status": "ok", "count": 5 }

// CORRECT — script uses unquoted keys
{ status: "ok", count: 5 }
```

**Do not use `return` — the last expression is the return value:**
```
// WRONG
return { status: "ok" }

// CORRECT
{ status: "ok" }
```

**Always import namespaces before using them:**
```
// WRONG — "Unknown identifier" error
let now = datetime.now()

// CORRECT
let dt = import("datetime")
let now = dt.now()
```

**No imperative loops — use array functions:**
```
// WRONG — for/while don't exist
for item in items { ... }

// CORRECT
let arr = import("array")
arr.map(items, fn(item) { ... })
```

## Script Authoring Rules

- **Always fetch `archagent describe scriptdocs` before writing scripts.** Do not invent syntax from memory.
- Prefer the dedicated top-level script commands over the generic `configs` resource unless the user explicitly wants config-managed files.
- Treat the language as functional and expression-oriented, not imperative.
- The last expression is the return value — there is no `return` keyword.
- Use `unwrap()` for error handling — never assume HTTP calls succeed.
- Use `println()` liberally while debugging, remove before deploying.
- If validation fails, rewrite toward the sample/reference instead of trial-and-error.

## Recovery Rules

- If a script fails validation, show the exact error. Common issues: missing imports, wrong function signatures, trying to use imperative loops.
- If `archagent run script` fails at runtime, check: are env vars set? Is the input JSON valid? Is the API reachable?
- If the user is unsure about syntax, always fall back to `archagent describe scriptdocs`.

## Response Rules

- Do not inspect or edit credential files directly — use the CLI only.
- Do not ask the user to pick raw subcommands when intent is clear.
- Keep responses concise and operational.
- Show the user a concrete script draft they can review, not abstract syntax explanations.