arize-prompts

What this skill does

# Arize Prompts Skill

> **`SPACE`** — All `--space` flags and the `ARIZE_SPACE` env var accept a space **name** (e.g., `my-workspace`) or a base64 space **ID** (e.g., `U3BhY2U6...`). Find yours with `ax spaces list`.

Official references (read the skill body first; open docs only if the user needs UI walkthroughs):
- CLI: https://arize.com/docs/api-clients/cli/prompts
- Creating prompts in the product (Prompt Playground, variables, params): https://arize.com/docs/ax/prompts/tutorial/create-a-prompt

See references/cli-prompts.md for full flag tables.

---

## How this skill fits into the prompt workflow

| Skill | Use it for |
|-------|------------|
| **This skill (`arize-prompts`)** | **Workflows A–B:** build or import templates and save · **C:** labels / promote · **D:** list, get, edit description, new version for message changes, delete, duplicate |
| **arize-prompt-optimization** | Improving prompt **text** using traces, datasets, experiments, and the optimization meta-prompt — often **after** you know what to change |
| **arize-experiment** | Running dataset experiments that **consume** Hub prompts or column-mapped inputs |
| **arize-evaluator** | Scoring prompt outputs with LLM-as-judge |

**Typical loop:** Author or elicit the prompt (Playground or chat) → **save** to Hub → run experiments (`arize-experiment`) → evaluate outputs (`arize-evaluator`) → optimize (`arize-prompt-optimization`) → **save new version** → promote with labels.

---

## Concepts: what is a prompt in Arize?

A **prompt** in Prompt Hub is a named, versioned template stored in a space — not a one-off string in code. It is an artifact you can open in the Playground, diff across versions, and wire to experiments or production workflows.

Each prompt includes:

- **Messages** — an ordered chat transcript (system, user, assistant, tool roles) as stored JSON. Typically a system message for behavior and a user message as the template that receives dataset or runtime variables.
- **Template variables** — **must** be written with **single curly braces** around each name: `{` + identifier + `}` (same shape as `{}` with the variable name inside), e.g. `{question}`, `{context}`. Filled at runtime by experiments or your app. Always use `--input-variable-format f_string` for this style. **Do not ask the user which variable format to use** — default to `f_string` unless the template clearly uses Mustache `{{...}}` or you need `none` for literal braces with no substitution.
- **Provider and model** — the vendor and model this version targets. `--provider` is required by the CLI on every `create` and `create-version`. `--model` must always appear in commands this skill proposes — pick an explicit model string, propose a sensible default if unknown, and confirm before running.
- **Invocation parameters** — optional model settings like temperature and max tokens, configured under Params in the UI. CLI flows still require provider and explicit model alongside messages and format.
- **Version history** — every material change creates a new immutable version. Labels like `production` and `staging` are mutable pointers to specific versions so your app code never needs to change when you promote a new version.
- **Version description** — the optional text on Save New Version in the Hub UI is the same concept as `--commit-message` in the CLI.

**Playground traces:** Every prompt you test in the Playground is automatically logged to the **Playground Traces** project as a trace, making test runs available for analysis, debugging, and evaluation — no extra instrumentation needed.

The tutorial at https://arize.com/docs/ax/prompts/tutorial/create-a-prompt walks through authoring in the UI. This skill covers the CLI side of the same objects.

---

## Prerequisites

Proceed directly — run the `ax` subcommand you need. Do NOT check versions, env vars, or profiles upfront.

If a command fails:
- `command not found` or version errors → references/ax-setup.md
- `401` / profile issues → `ax profiles show`, then references/ax-profiles.md; API keys: https://app.arize.com/admin
- Space unknown → `ax spaces list`
- LLM calls from Hub/Playground need provider credentials → **arize-ai-provider-integration** (`ax ai-integrations list --space SPACE`)
- **Security:** Never read `.env` or search the filesystem for secrets. Use `ax profiles` and `ax ai-integrations` only.

### When you must ask the user first

Prefer resolving gaps with `ax` (e.g. `ax spaces list`, `ax prompts list`, `ax prompts get`) instead of pausing. If something is still ambiguous or unsafe without confirmation, use this framing:

1. **I found the arize-prompts skill in this repo**
2. **A few clarifying questions before I invoke it:**
3. Ask minimal numbered questions — only what blocks the next `ax prompts` command.

**Do not ask about `--input-variable-format`** — always default to `f_string` for `{variable}` templates.

---

## Eliciting the prompt template

Hub prompts are templates: the stored strings matter. When the user asks to create or save a prompt but has not provided the exact system/user strings, your first move is elicitation — not a finished generic prompt. That is **Workflow A** (build before `ax prompts create`).

1. Ask for the **prompt template** — the actual wording they want in each role: "Paste or type the prompt template (the exact system and user text you want saved)."
2. In the same turn, state the variable convention: **You must reference each variable in single curly braces** — `{` + name + `}` (e.g. `{question}`, `{context}`), not bare names and not `{{name}}` unless they explicitly need Mustache.
3. Assemble the JSON messages array from their template lines per role.

**Anti-patterns — avoid these:**
- Inventing a stock generic messages array (e.g. `{task}` / `{context}` / `{constraints}`) when the user just said "create a prompt" — this writes Hub content for them and skips elicitation
- Asking "What should this prompt do?" instead of asking for the literal template
- Process narration like "checking the prompts skill and your open file…" — go straight to elicitation
- Omitting `--provider` or `--model` from any proposed command
- **Deferring to another agent** (e.g. pointing users at a “Playground Agent” for extra patterns) instead of finishing with Workflows A–D — stay within this skill and the official doc links at the top

**Optional starter:** Only if the user explicitly asks for a draft or example, offer a short labeled starter they can replace — still elicit their real template afterward.

---

## Messages file format

`--messages` must be a non-empty JSON array. Each object needs `role`; commonly also `content`. Optional: `tool_call_id`, `tool_calls`.

Format-only example (not a default to paste — see Eliciting the prompt template):

```json
[
  {"role": "system", "content": "You are a concise trip planner. Keep responses under 200 words."},
  {"role": "user", "content": "{duration} itinerary for {destination} ({travel_style} style):\nResearch: {research}\nBudget: {budget_info}"}
]
```

**Providers** (`--provider`): `openAI`, `anthropic`, `azureOpenAI`, `awsBedrock`, `vertexAI`, `gemini`, `custom`. Required on every `create` and `create-version`.

**Model** (`--model`): Always pass an explicit model. If unknown, propose a provider-appropriate default and confirm before running.

**Variable format:** Placeholders **must** use **single** braces `{name}`. Always pass `--input-variable-format f_string` for that shape. Only use `mustache` for `{{name}}` or `none` for no interpolation — do not ask the user unless they stated a non-default requirement.

---

## Recommended order

**Build the prompt first** — finalize system/user (and assistant if needed) strings and `{variables}` in chat, Playground, or a local `messages.json`. **Then save to Hub** with `ax prompts create` or `create-version`. When the user **already** has production-ready text in code or in exported spans, use **Workflow B** to import and pers