# Build your first playbook

A **playbook** is a saved instruction set: a name, a short description, a curated list of datablocks, and optional guidance for the AI. When you ask a question that matches a playbook, SMAQ surfaces it at the top of the chat — one click and it runs your investigation the way you'd run it yourself.

### Why playbooks?

Every analyst has their own recipe for the questions they get asked the most — "Why did ROAS drop?", "What's underperforming this week?", "What should my next campaign say?" Universal playbooks don't work because nobody knows your business and your clients better than you. Playbooks let you teach SMAQ AI your recipe once and reuse it forever.

### What's in a playbook?

1. **Name** — short, descriptive label so you can find it later.
2. **Description** — a sentence about what it does and when it's useful. The AI uses this to decide whether to suggest the playbook.
3. **Datablocks** — the queries the AI should run. These are the "actions" of the playbook.
4. **Additional guidelines** — free-text instructions: what to focus on, what kind of insight to surface, what format the response should take, what language to write in.

***

### Step 1 — Create a new playbook

1. Click **Playbooks** in the side menu.
2. Click **Create new playbook**.
3. Give it a name (e.g. "Weekly performance review") and a description (e.g. "Run every Monday — covers Google Ads, Meta, GA4; highlights week-over-week changes and flags anything outside ±20%").

> **\[Screenshot needed]** Empty new-playbook form with name and description filled in.

### Step 2 — Add datablocks

1. Use the search to find datablocks that fit your investigation.
2. Click the **+** button next to each datablock to add it.
3. Click **-** to remove anything you added by mistake.
4. Click **Save**.

> **\[Screen video needed]** Searching for "weekly performance," adding three datablocks to the playbook, then saving. \~30 seconds.

### Step 3 — Add additional guidelines (optional)

Click into the **Additional guidelines** section and add instructions like:

* "Always compare against the same period last week and call out changes ≥ ±20%."
* "Keep the response under 200 words."
* "Reply in 繁體中文."
* "End with a one-line recommendation for what to do next."

These guidelines apply every time the playbook runs.

### Step 4 — Execute the playbook from chat

Open the chat in the same project. Ask a related question — e.g. "How did we do last week?" SMAQ recognizes the playbook applies and surfaces it at the top of the suggestions. Click it to run.

> **\[Screenshot needed]** Chat with the playbook suggested at the top of the message thread, just above a user prompt.

> **\[Screenshot needed]** Playbook execution result with the AI's structured analysis displayed.

### Step 5 — Share with your team

To make the playbook available to others in your organization:

1. Open the playbook.
2. Toggle **Org-wide sharing** on.

The playbook now shows up in the **Organization Gallery** for every project editor in your org.

> **\[Screenshot needed]** Playbook detail with the Org-wide sharing toggle on.

### Step 6 — Copy a shared playbook into another project

1. Open **Playbooks** in any project.
2. Switch to the **Organization Gallery** tab.
3. Find the playbook and click **Copy to project**.

A copy lands in **My Playbooks** for that project — you can edit it without affecting the shared original.

> **\[Screenshot needed]** Organization Gallery with three shared playbooks and "Copy to project" buttons visible.

### Tips

* **Start with one playbook**, refine it over a week of use, then build more.
* **Keep playbooks narrow.** "Weekly Meta review" is better than "Full marketing review" — narrow playbooks produce sharper outputs.
* **Use the guidelines field aggressively.** This is where you embed your team's house style and quality bar.

### What's next

* [Playbooks reference](/documentation/features/chat/playbooks.md) — full feature documentation.
* [What SMAQ AI can do](/documentation/features/chat/capabilities.md) — agent capabilities the playbook orchestrates.
* [Chat with SMAQ AI](/documentation/get-started/tutorials/chat-with-smaq-ai.md) — back to the chat tutorial.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.smaq.io/documentation/get-started/tutorials/build-your-first-playbook.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.