Parameters

What Are Parameters?

Parameters turn static skills into flexible, reusable queries. Instead of creating separate skills for "active users on Pro" and "active users on Business," you create one skill with a plan parameter and let users specify the value at runtime.

When a user runs /alice users --plan=pro, alice substitutes the plan value into your query before execution. Parameters work across all trigger types: slash commands, scheduled reports, and monitors.

Adding Parameters in the Builder

Parameters are configured in the Setup step of the skill builder. Click Add in the Parameters section to create a new parameter.

Every parameter has five properties:

Naming Rules

Parameter names must be lowercase and can only contain letters, numbers, hyphens, and underscores. They are limited to 30 characters. Good names are short and descriptive:

• plan -- not subscription_plan_type
• days -- not number_of_days_to_look_back
• status -- not the_status_filter

The name you choose becomes the flag users type in Slack, so brevity matters.

Parameter Types

String

The default type. Accepts any text value. Use for IDs, emails, plan names, or freeform text.

/alice users --email=jane@acme.com

Default value: any text string, or leave blank for no default.

Number

Accepts integer or decimal values. Validated at runtime -- alice rejects non-numeric input before executing the query.

/alice revenue --days=30

Default value: a numeric value, or leave blank for no default.

Date

Accepts date values with built-in presets. The builder offers common defaults:

Date values are formatted as YYYY-MM-DD when passed to your query. In Slack, users can type dates naturally:

/alice signups --since=2025-01-01
/alice signups --since=yesterday

Boolean

A true/false toggle. The builder shows a dropdown with two options. In Slack, users pass true or false:

/alice users --include-churned=true

Default value: true or false. Defaults to true when first created.

Select

A constrained list of allowed values. When you choose the Select type, an additional Options field appears where you enter comma-separated values.

/alice revenue --currency=eur

If a user passes a value not in the options list, alice returns an error before executing the query.

Using Parameters in Queries

How you reference parameters depends on your query mode.

SQL Queries (Supabase)

In SQL mode, parameters are bound using positional placeholders: $1, $2, $3, and so on. The position matches the order the parameters appear in the builder.

SELECT email, plan, created_at
FROM users
WHERE plan = $1
  AND created_at > now() - interval '1 day' * $2
ORDER BY created_at DESC
LIMIT 20

If you have two parameters -- plan (first) and days (second) -- then $1 maps to plan and $2 maps to days.

Important: always use $N positional binding. Never use :paramName or string interpolation. Positional binding is parameterized, which prevents SQL injection and ensures your query is safe. See Query Syntax for full details.

The builder shows a help hint below each parameter:

Use as $1 in SQL or --plan=value in the slash command.

Visual Builder (Stripe)

When using the Stripe visual builder, parameters bind to filter values. In the filter configuration, select a parameter name instead of typing a static value. At runtime, the user's parameter value is substituted into the API filter.

For example, a Stripe Customers query with a filter email = $email lets the user run:

/alice customer-lookup --email=jane@acme.com

Stripe Metric Blocks

When using Stripe metric blocks, some blocks accept parameters for currency, limit, or time period. These are configured through the metric block's own parameter UI, not the general parameters editor. See Creating a Skill for details.

Combined Queries

In combined queries, parameters are shared across all query steps. If you define a days parameter, every step in the combined query can reference it. In SQL steps, use the same $N binding; in Stripe steps, bind it to a filter.

Running Skills with Parameters

In Slack

Pass parameters as --name=value flags after the skill slug:

/alice churn-risk --days=30 --plan=pro

Multiple parameters can be passed in any order:

/alice users --plan=pro --days=7
/alice users --days=7 --plan=pro

Both produce the same result. For string values with spaces, wrap them in quotes:

/alice search --query="payment failed"

Boolean parameters accept true or false:

/alice report --include-trials=false

Viewing Available Parameters

Run any skill with --help to see its parameter documentation:

/alice churn-risk --help

Alice responds with the skill description, all available parameters, their types, whether they are required, and their default values. This is generated from the name, type, and description you set in the builder.

From the Dashboard

When running a skill from the dashboard, parameter inputs appear as form fields. The type determines the input widget: text input for strings, number spinner for numbers, date picker for dates, toggle for booleans, and dropdown for selects.

In Scheduled Reports

Scheduled reports use the default values for all parameters. If a parameter has no default and is required, the scheduled run will fail. Always set defaults for parameters on skills you plan to run on a schedule.

Validation and Error Handling

Alice validates parameter values before executing any query:

• Required parameters: If a required parameter is missing and has no default, alice returns an error message listing the missing parameter.
• Type validation: Number parameters reject non-numeric input. Boolean parameters only accept true or false. Select parameters only accept values from the defined options list.
• Unknown flags: If a user passes a --flag that does not match any defined parameter, alice ignores it silently. This prevents typos from breaking existing workflows.

When validation fails, alice responds in Slack with a clear error message:

Missing required parameter: --plan
Run /alice users --help for usage info.

Best Practices

Use descriptive defaults. If 80% of your team runs /alice users --days=30, set 30 as the default so they can just type /alice users.

Keep parameter counts low. One to three parameters is comfortable. If you need more than five, consider whether the skill is trying to do too much. Split it into multiple focused skills instead.

Document with descriptions. The description field powers the --help output. Write clear, specific descriptions: "Number of days to look back" is better than "days."

Prefer select over string for constrained values. If your parameter only accepts a few known values (plan tiers, currencies, statuses), use the Select type. It prevents typos and makes --help output more informative.

Set defaults for scheduled skills. Any skill running on a cron schedule executes without user input. Every required parameter needs a default, or the run will fail silently.

Order parameters by frequency of use. The first parameter gets $1 in SQL. Put the most commonly overridden parameter first so advanced users can rely on position.

Related

• Creating a Skill -- full walkthrough of the skill builder
• Query Syntax -- SQL and Stripe query reference
• Slash Commands -- how commands work in Slack
• Combined Queries -- sharing parameters across multi-source skills
• Scheduled Reports -- how defaults apply to automated runs
• Formatting Output -- configure how results display
• AI Skill Generation -- auto-generating skills with parameters