Manage MotherDuck Guides
Source Of Truth
- Prefer the current MotherDuck Guides documentation and MCP tool descriptions.
- For analytical queries through MCP, call
get_query_guide before writing SQL, then traverse only relevant topics and Guides.
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.
- 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.
Workflow
- Inspect
get_query_guide or list_guides to understand the visible topic tree and avoid duplication.
- Read the relevant Guide versions and referenced objects before drafting a change.
- Choose the narrowest useful topic; leave the topic empty only for organization-wide orientation.
- Draft concise Markdown that maps business language to exact catalog objects and validated SQL.
- For a create or update request, apply the change through MCP or the documented SQL function and read it back.
- 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 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 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 for validating referenced catalog objectsmotherduck-query for testing SQL and applying Guide-aware analysismotherduck-create-dive and motherduck-create-flight for reserved-topic conventionsmotherduck-security-governance for organization visibility and permission boundaries
1---2name: motherduck-manage-guides3description: Read or maintain MotherDuck Guides for business definitions, join rules, and reusable warehouse conventions.4license: MIT5---6
7# Manage MotherDuck Guides
8
9## Source Of Truth
10
11- Prefer the current MotherDuck Guides documentation and MCP tool descriptions.
12- For analytical queries through MCP, call `get_query_guide` before writing SQL, then traverse only relevant topics and Guides.
13- `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.
14
15## Default Posture
16
17- Keep one short root orientation Guide only when its guidance applies broadly. Put domain-specific knowledge under shallow, descriptive topics.
18- Default new Guides to `access = 'user'`. Organization visibility requires an explicit request and the required admin permission.
19- Write one coherent subject per Guide, with a discriminating title and description. Lead with rules, tested SQL, and named pitfalls.
20- Attach references to the databases, shares, schemas, tables, columns, Dives, Flights, or Guides the content governs so agents discover it at the right time.
21- Validate referenced objects and executable SQL against the live workspace before presenting a Guide as trustworthy.
22- Use version comments to explain why guidance changed. Read before update and avoid overwriting concurrent work.
23
24## Workflow
25
261. Inspect `get_query_guide` or `list_guides` to understand the visible topic tree and avoid duplication.
272. Read the relevant Guide versions and referenced objects before drafting a change.
283. Choose the narrowest useful topic; leave the topic empty only for organization-wide orientation.
294. Draft concise Markdown that maps business language to exact catalog objects and validated SQL.
305. For a create or update request, apply the change through MCP or the documented SQL function and read it back.
316. 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.
32
33For 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 or expanding visibility beyond the authorized audience. An explicit organization-publication request already authorizes that audience, subject to admin permission.
34
35## References
36
37Read only the reference sections needed for the current task.
38
39- Read `references/GUIDES_PLAYBOOK.md` for topic design, access governance, references, MCP/SQL operations, versioning, and quality checks.
40
41## Related Skills
42
43Load related skills only for missing capabilities; reuse established context.
44
45- `motherduck-explore` for validating referenced catalog objects
46- `motherduck-query` for testing SQL and applying Guide-aware analysis
47- `motherduck-create-dive` and `motherduck-create-flight` for reserved-topic conventions
48- `motherduck-security-governance` for organization visibility and permission boundaries
motherduckdb