# motherduck-manage-guides
> Read or maintain MotherDuck Guides for business definitions, join rules, and reusable warehouse conventions.
Read or maintain MotherDuck Guides for business definitions, join rules, and reusable warehouse conventions.

[Workflow skill](/sql-reference/agent-skills/#workflow-skills) · [View source on GitHub](https://github.com/motherduckdb/agent-skills/tree/v3.0.0/skills/motherduck-manage-guides)

:::info

This page shows the skill's `SKILL.md`: the instructions a coding agent loads when a task matches the description above. To install every MotherDuck skill in Claude Code, Codex, Cursor, or Gemini CLI, see [Install MotherDuck Skills](/key-tasks/ai-and-motherduck/agent-skills/). To install only this skill with the [Skills CLI](https://github.com/vercel-labs/skills), run:

```bash
npx -y skills add motherduckdb/agent-skills --skill motherduck-manage-guides --yes --global
```

This skill relies on [`motherduck-explore`](/sql-reference/agent-skills/motherduck-explore/) and [`motherduck-query`](/sql-reference/agent-skills/motherduck-query/). Install those too, or install the full catalog.

:::

## Source of truth

- Prefer the current MotherDuck Guides documentation and MCP tool descriptions.
- When MotherDuck MCP is available and the SQL answers a business question, call `get_query_guide` first, then read only the relevant Guide topics and validate their claims against the live schema.
- `get_dive_guide` and `get_flight_guide` automatically include summaries from the reserved `dives` and `flights` topics; do not load those topics separately unless deeper context is needed.

## Default posture

- Keep one short root orientation Guide only when its guidance applies broadly. Put domain-specific knowledge under shallow, descriptive topics.
- Default new Guides to `access = 'user'`. Organization visibility requires an explicit request and the required admin permission; change it with `set_guide_access` (MCP) or `--access` on `motherduck guide push`.
- Document tables that Flights create under the `data-sources` topic (not `flights`, which holds authoring conventions): source, purpose, grain, key columns, transformations, refresh behavior, and caveats, with references to the table, its producing Flight, and any consuming Dive. Create these with `user` access; when the table's database has an owned share, propose `organization` access and apply it only on request.
- Write one coherent subject per Guide, with a discriminating title and description. Lead with rules, tested SQL, and named pitfalls.
- Attach references to the databases, shares, schemas, tables, columns, Dives, Flights, or Guides the content governs so agents discover it at the right time.
- Validate referenced objects and executable SQL against the live workspace before presenting a Guide as trustworthy.
- Use version comments to explain why guidance changed. Read before update and avoid overwriting concurrent work.
- When a shell is available and Guides should live in Git or be reviewed like code, use `motherduck guide` (see [`motherduck-cli`](/sql-reference/agent-skills/motherduck-cli/)): edit `guide.md` locally, `push` with `--version-description`, and pass the commit SHA as `--external-id` so each version traces to a change.

## Workflow

1. Inspect `get_query_guide` or `list_guides` to understand the visible topic tree and avoid duplication.
2. Read the relevant Guide versions and referenced objects before drafting a change.
3. Choose the narrowest useful topic; leave the topic empty only for organization-wide orientation.
4. Draft concise Markdown that maps business language to exact catalog objects and validated SQL.
5. For a create or update request, apply the change through MCP or the documented SQL function and read it back.
6. Verify metadata, access, references, current version, and change comment. For query work, follow the Guide and still validate the resulting SQL against the live schema.

For answer, review, or planning requests, inspect and draft without creating or modifying Guides. For explicit create/update requests, perform the in-scope mutation and verify it; ask before deletion (`delete_guide`) or expanding visibility beyond the authorized audience. An explicit organization-publication request already authorizes that audience, subject to admin permission.

## References

Read only the reference sections needed for the current task.

- Read [`references/GUIDES_PLAYBOOK.md`](https://github.com/motherduckdb/agent-skills/blob/v3.0.0/skills/motherduck-manage-guides/references/GUIDES_PLAYBOOK.md) for topic design, access governance, references, MCP/SQL operations, versioning, and quality checks.

## Related skills

Load related skills only for missing capabilities; reuse established context.

- [`motherduck-explore`](/sql-reference/agent-skills/motherduck-explore/) for validating referenced catalog objects
- [`motherduck-query`](/sql-reference/agent-skills/motherduck-query/) for testing SQL and applying Guide-aware analysis
- [`motherduck-create-dive`](/sql-reference/agent-skills/motherduck-create-dive/) and [`motherduck-create-flight`](/sql-reference/agent-skills/motherduck-create-flight/) for reserved-topic conventions
- [`motherduck-security-governance`](/sql-reference/agent-skills/motherduck-security-governance/) for organization visibility and permission boundaries

## Files in this skill

The agent reads these files when the instructions above point to them.

- [`agents/openai.yaml`](https://github.com/motherduckdb/agent-skills/blob/v3.0.0/skills/motherduck-manage-guides/agents/openai.yaml)
- [`references/GUIDES_PLAYBOOK.md`](https://github.com/motherduckdb/agent-skills/blob/v3.0.0/skills/motherduck-manage-guides/references/GUIDES_PLAYBOOK.md)

## Docs this skill draws on

- [Using Guides to improve AI query accuracy and personalize agents](https://motherduck.com/docs/key-tasks/guides/)
- [Bootstrap Guides from the context you already have](https://motherduck.com/docs/key-tasks/guides/bootstrap-guides-with-an-ai-agent/)
- [get_query_guide](https://motherduck.com/docs/sql-reference/mcp/guides/get-query-guide/)
- [list_guides](https://motherduck.com/docs/sql-reference/mcp/guides/list-guides/)
- [create_guide](https://motherduck.com/docs/sql-reference/mcp/guides/create-guide/)
- [guide](https://motherduck.com/docs/sql-reference/motherduck-cli/guide/)


---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

URL-encode query parameter values and send a GET request:

```text
GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fsql-reference%2Fagent-skills%2Fmotherduck-manage-guides%2F&page_title=motherduck-manage-guides&text=<url-encoded user feedback, max 2000 characters>
```

Optionally append `&source=<url-encoded interface identifier>` such as `claude.ai` or `chatgpt`.

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed query parameters, and `429` when rate-limited.
