build-script

Files (1)

• SKILL.md

SKILL.md (first lines)

# ArchAstro Script Builder

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

This skill assumes the ArchAstro CLI is already installed and authenticated. Use the `/archastro:install` and `/archastro:auth` commands in this same plugin instead of trying to install or authenticate the CLI manually inside this skill.

## 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: `archastro 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:

```
archastro auth status
archastro 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

### CLI not installed or too old

Before any script work, verify the CLI:

- Read `plugin-compatibility.json` from the plugin root.
- Prefer `plugins.archastro.minimumCliVersion`, fall back to the top-level `minimumCliVersion`.
- Run `archastro --version`. If missing or older than the resolved minimum, direct the user to `/archastro:install`.
- If authentication or app selection is missing, direct the user to `/archastro:auth`.

### 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:
```
archastro 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:
```
archastro 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`:
```
archastro 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:
```
archastro list events
archastro 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).body

{
  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`, `flat`)
- `string` — String operations (`split`, `trim`, `lowercase`, `uppercase`, `includes`)
- `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`, `isOk`, `isErr`)
- `email` — Email sending
- `jwt` — JWT token operations

From ArchAstro/archastro, MIT.

More from ArchAstro/archastro