Best Practices

Practical guidance for creating reliable Playbooks

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 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.