Skip to main content

Add Dive styles and Flight conventions

Agents follow MotherDuck's default instructions when they build Dives and Flights. Use a Guide to add conventions such as your organization's color palette, number formatting, preferred chart types, page organization, drilldowns, Flight naming, or scheduling standards.

Guides are private by default. You can keep them private or publish them to your organization.

Prerequisites​

  • A MotherDuck account with the MCP server connected to an AI client like Claude, Cursor, or Claude Code
  • Permission to publish organization-wide Guides, if you want other members of your organization to use the conventions

How agents apply these Guides​

Before building a Dive or Flight, an agent calls:

Each response also lists the Guides under its reserved dives or flights topic by title and description. The agent opens a relevant Guide with get_guide.

Describe what your Guide changes and omit conventions already covered by the built-in instructions.

You can create multiple Guides for different use cases. For example:

  • Executive reporting: Brand colors, compact KPIs with sparkline charts, and drilldowns for period-over-period changes
  • Operations monitoring: Dense layouts, status colors, and hourly timestamps
  • Customer reporting: A customer's palette, logo placement, and number formats

The agent uses each Guide's title and description to decide which conventions apply. Use the title to identify the convention set and the description to state when to use it, including the audience or use case. You can also request a Guide by title:

Create a Dive showing weekly revenue using the "Executive reporting" style.

Create and test a Dive Guide​

  1. Ask your agent to create a private Guide under the dives topic. Include the conventions you want it to apply:

    Create a private Guide under the "dives" topic with these conventions:

    - Use our brand palette instead of the MotherDuck default: primary
      #1d4ed8, positive #15803d, and negative #b91c1c.
    - Format currency in thousands with no decimal places.
    - Put the reporting period in the page subtitle, not the chart title.
    - Add a sparkline to each KPI card.
    - For week-over-week, month-over-month, or quarter-over-quarter changes,
      include a drilldown showing the underlying time series.

    Show me the proposed title, description, and content before saving it.

    You can also use an existing Dive as the starting point:

    Review the Dive "<dive_name_or_id>" and create a private Guide under the
    "dives" topic. Capture its reusable styling, preferred chart types, page
    organization, formatting, and interaction patterns. Generalize those
    conventions instead of copying the Dive's data or task-specific content.

    This Guide should apply when <usage_scenario>. Show me the proposed title,
    description, and content before saving it.

  2. Review the proposed Guide, then tell the agent to save it.

  3. Start a new chat with the MotherDuck MCP server connected. Ask the agent to build a Dive without repeating your conventions.

  4. Check the Dive against the Guide. If the agent didn't apply it, ask it to call get_dive_guide and show the Dive guides section. Confirm that:

  • The Guide uses the exact topic dives.
  • Its title identifies the convention set, and its description states when to use it.
  • The agent opened the Guide before building the Dive.

You can update the Guide after creating it. Refine it if the test shows that it doesn't capture the intended output, or revise it when your conventions change.

Create and test a Flight conventions Guide​

Use the flights topic for reusable Flight authoring conventions. These can cover naming, schedules, secret handling, observability, or ingestion patterns.

Create a private Guide under the "flights" topic with these conventions:

- Name scheduled Flights <source>-to-<target>.
- Run hourly schedules at :15 past the hour.
- Store credentials in MotherDuck secrets. Don't put credentials in source code.
- Write each run summary to ops.main.flight_runs.

Show me the proposed title, description, and content before saving it.

Test it in a new chat by asking the agent to author a Flight without repeating the conventions. If the agent doesn't select the expected Guide, its description may not state clearly enough when to use it. Ask the agent to call get_flight_guide and check the Flight guides section, then refine the description if needed.

Optional: publish a Guide to your organization​

After testing a Guide, you can make it available to everyone in your organization. Ask your agent:

Publish the "<guide_title>" Guide to my organization.

This action requires admin permission. Publishing doesn't change ownership; only the creator can delete the Guide.

The dives and flights topics don't appear in get_query_guide, but you can browse them with list_guides(topic = 'dives') or list_guides(topic = 'flights').