> For the complete documentation index, see [llms.txt](https://docs.airops.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.airops.com/actions/playbooks/best-practices.md).

# Best Practices

Use these practices to make Playbooks easier to run, review, and improve.

## Start with Brand Kit and Prompt coverage

A current Brand Kit and complete Prompt coverage are the two biggest quality levers. Confirm both before optimizing the Playbook structure.

## Start with less instruction

Give the agent enough direction to understand the goal, then add constraints where you need predictable behavior. Overly prescriptive instructions can reduce the agent's ability to reason through edge cases.

## Organize Sections by phase

Use phases like **Research**, **Draft**, and **Review**. Avoid organizing Sections around people, such as "Strategist Section" or "Editor Section." Phase-based structure is easier to reuse and easier to review.

## Format each Section consistently

Give each Section a predictable internal structure so the agent understands the goal, the reviewer can scan the work, and downstream Sections know which Artifact to use.

A strong Section usually includes:

* **Objective:** One or two sentences that define what this Section should accomplish.
* **Inputs and references:** The Inputs, Artifacts, Brand Kit fields, Tools, or Knowledge Bases the Section should use. Insert these with the slash menu when possible.
* **Instructions:** Numbered steps for the work the agent should perform. Keep these focused on decisions, constraints, and source preferences.
* **Output:** The Artifact the Section should write, plus the required format, such as a Markdown report, JSON map, or final article.

Use the same pattern across Sections. For example, a research Section might state the objective, reference the target prompt and Brand Kit, list the research steps, then write the findings to **AI & Google Results.md**. A drafting Section might reference **Content Outline.md** and **Topic Research.md**, list writing requirements, then write the draft to **Article Draft.md**.

## Use Sections as checkpoints

Add a Section when you need:

* A discrete Artifact.
* A pause for Human Review.
* A clean reference point for later Sections.

## Only write Artifacts when you need persistence

Context carries between Sections automatically. Use Artifacts when an output needs to be stored, shared, or referenced later.

## Reference Knowledge Bases by name

Pick the specific Knowledge Base in the step's Knowledge Base picker. Auto-selection or all-Knowledge-Base search can retrieve from the wrong source.

## Reference Artifacts by name

Artifact names are stable. Filenames can change. Use the slash menu to insert Artifact references by name in downstream Sections.

## Keep publishing separate from content creation

Use Playbooks to create, refresh, review, and prepare content. Publish from a Grid column, a separate publishing Playbook, or a CMS MCP after review. This keeps editorial review, CMS field mapping, and publish tracking easier to control.

When a Playbook or CMS MCP publishes or refreshes a page, use the AirOps MCP `track_aeo_page_content_update` tool with the page URL and update type so AirOps Insights can connect future AI visibility, citation, mention, and traffic changes to that content update.

## Pair opportunity-finding and output-producing Playbooks

Let one Playbook monitor data and find opportunities, then let a separate action Playbook produce the output. This makes each Playbook easier to reason about, review, and iterate.

## Ask Quill to translate Workflow prompts

When you migrate a Workflow, paste the original prompt with full context and ask [Quill](/quill/quill.md) to translate it into a concise agent instruction. Trim the result from there.

## Keep proposed changes human-reviewed

Well-designed Playbooks suggest changes for human approval instead of applying them automatically when judgment matters. This pattern builds trust, catches edge cases, and keeps stakeholders in the loop.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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.airops.com/actions/playbooks/best-practices.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.