Motherduck Partner Delivery

Partner Delivery

Use this skill when a consultancy, implementation partner, or multi-client product team needs a repeatable MotherDuck delivery pattern across several clients.

This is a use-case skill. It orchestrates motherduck-connect, motherduck-explore, motherduck-model-data, motherduck-query, motherduck-share-data, and motherduck-create-dive.

Start Here: Is a MotherDuck Server Active?

Always determine this first.

• If a remote MotherDuck MCP server or local MotherDuck server is active, use it.
• If the delivery will run against an existing workspace, ask which client databases or workspaces are already in scope.
• Explore the live setup when available:
• current client database boundaries
• regional layout
• existing service-account or share boundaries
• reusable schemas vs client-specific schemas

Use that discovery to decide what can be standardized and what must stay client-specific.

If no server is active, ask for representative client patterns and regions before proposing the standard delivery model.

Use This Skill When

• The user is delivering MotherDuck solutions across multiple clients.
• The user needs region-aware, repeatable architecture.
• The user needs standard provisioning with explicit client exceptions.
• The goal is a reusable delivery pattern, not a one-off single-client implementation.

Delivery Defaults

• structural isolation over query-time tenant filtering
• one client database or stronger boundary per client
• shared architecture, client-specific schema
• explicit sharing and revocation per client
• versioned templates for provisioning, validation, handoff, and exception tracking

Workflow

1. Confirm whether live MotherDuck discovery is available. 2. Classify the client patterns. 3. Inspect the existing regional and database layout if available. 4. Standardize the architecture and provisioning path. 5. Define the repeatable validation pack for every client environment. 6. Document client-specific exceptions. 7. Produce the handoff assets and validation checks.

When this skill produces a native DuckDB (md:) connection, watermark it with custom_user_agent=agent-skills/2.3.0(harness-<harness>;llm-<llm>). If metadata is missing, fall back to harness-unknown and llm-unknown.

Output

The output of this skill should be:

• the default multi-client pattern
• the standard provisioning checklist
• the region and isolation posture
• the client-specific exceptions

If the caller explicitly asks for structured JSON, return raw JSON only with no Markdown fences or prose before/after it. This is mainly for automated tests, regression checks, or downstream tooling that needs a stable machine-readable shape. Normal human-facing use of the skill can stay in prose unless JSON is explicitly requested.

Use this exact top-level shape when JSON is requested:

{
  "summary": {},
  "assumptions": [],
  "implementation_plan": [],
  "validation_plan": [],
  "risks": []
}

References

Read this as reference, not as a script to execute:

• references/PARTNER_DELIVERY_GUIDE.md -- default multi-client pattern, standardize-versus-client-specific split, shares-versus-Dives-versus-apps choice, region/compliance handling, and provisioning starters

Runnable Artifact

• artifacts/client_delivery_example.py -- MotherDuck-backed Python example showing one database namespace per client and a simple validation pass across client environments
• artifacts/client_delivery_example.ts -- TypeScript companion artifact with the same delivery output contract

Run it with:

uv run --with duckdb python skills/motherduck-partner-delivery/artifacts/client_delivery_example.py

Run the same artifact against temporary MotherDuck databases:

MOTHERDUCK_ARTIFACT_USE_MOTHERDUCK=1 \
uv run --with duckdb python skills/motherduck-partner-delivery/artifacts/client_delivery_example.py

Validate the TypeScript companion artifact:

uv run scripts/test_typescript_artifacts.py

Related Skills

• motherduck-connect -- standardize the connection path
• motherduck-explore -- inspect existing client workspaces and boundaries
• motherduck-model-data -- design client-specific schemas
• motherduck-query -- validate core metrics and data contracts
• motherduck-share-data -- publish governed share boundaries
• motherduck-create-dive -- create repeatable client-facing answer surfaces when needed

<!-- Preserved detailed implementation guidance moved from SKILL.md so the main skill can stay concise. -->

Partner Delivery

Use this skill when a consultancy, implementation partner, or multi-client product team is delivering MotherDuck solutions repeatedly across customer accounts. Partners often work across different industries — retail, healthcare, fintech, logistics — so client data models and schemas will differ by industry. What stays consistent is the architecture: isolation, provisioning, connection patterns, and deployment structure. This skill focuses on the repeatable infrastructure layer, not the client-specific data model.

Contents

• Source of truth and verified delivery defaults
• Validation Signals (maintainer/reviewer checks)
• Language focus and starter snippets (TypeScript client config, Python provisioning/validation)
• Public product anchors (Hypertenancy, read scaling, Dives, shares)
• Default multi-client pattern
• What to standardize vs keep client-specific
• Shares vs Dives vs full apps
• Region and compliance handling

Source Of Truth

• Prefer current MotherDuck public docs and product pages.
• If the MotherDuck MCP ask_docs_question feature is available, use it first.
• Verify anything commercial, regional, or security-sensitive against live public materials before giving a definitive answer.

Verified Delivery Defaults

Defaults that hold across partner deliveries:

• standardize the isolation and provisioning pattern, not the client schema
• keep one database namespace and one credential boundary per client unless the customer has a stronger requirement
• make region choice explicit in the delivery contract
• treat client-specific ingestion or app code as add-ons around the core multi-client isolation model

Validation Signals

Use these signals for testing, review, and regression checks. They are not an instruction to include a separate "Validation Signals" section in normal user-facing replies.

• run artifacts/client_delivery_example.py against temporary MotherDuck databases
• verify each client gets its own database entry in the output payload
• verify the delivery pattern still states one database and one credential boundary per client
• treat any partner template that assumes a shared client schema as a regression

Language Focus: TypeScript/Javascript and Python

• Prefer TypeScript/Javascript for reusable partner delivery assets in:
• product backends
• starter APIs
• admin or client provisioning tools
• Prefer Python for:
• implementation scripts
• migration helpers
• validation tooling
• operational handoff assets
• When producing a partner-ready solution, it is often best to provide:
• a TypeScript/Javascript app skeleton
• Python validation or migration helpers

TypeScript/Javascript Starter

type ClientConfig = {
  slug: string;
  database: string;
  region: "us-east-1" | "eu-central-1";
  serviceAccountEnvVar: string;
};

const clients: ClientConfig[] = [
  { slug: "acme", database: "customer_acme", region: "us-east-1", serviceAccountEnvVar: "ACME_MD_TOKEN" },
];

Python Provisioning and Validation Starter

import duckdb

PARTNER_USER_AGENT = "agent-skills/2.3.0(harness-<harness>;llm-<llm>)"


def provision_client(conn: duckdb.DuckDBPyConnection, slug: str, region: str) -> dict:
    """Provision a new client database with the standard schema."""
    db_name = f"customer_{slug}"
    conn.execute(f"CREATE DATABASE IF NOT EXISTS {db_name}")
    conn.execute(f"""
        CREATE TABLE IF NOT EXISTS "{db_name}"."main"."usage_daily" (
            usage_date DATE NOT NULL,
            metric_name VARCHAR NOT NULL,
            metric_value DOUBLE NOT NULL,
            updated_at TIMESTAMP DEFAULT current_timestamp
        )
    """)
    conn.execute(f"""
        COMMENT ON TABLE "{db_name}"."main"."usage_daily"
        IS 'Daily usage metrics for client {slug}'
    """)
    return {"slug": slug, "database": db_name, "region": region}


def validate_client_database(conn: duckdb.DuckDBPyConnection, database_name: str) -> dict:
    """Validate that a client database has the expected tables and row counts."""
    tables = conn.sql(f"""
        SELECT table_name, estimated_size
        FROM duckdb_tables()
        WHERE database_name = '{database_name}'
    """).fetchall()
    return {
        "database": database_name,
        "table_count": len(tables),
        "tables": [{"name": t[0], "estimated_size": t[1]} for t in tables],
        "pass": len(tables) > 0,
    }


def validate_all_clients(clients: list[dict]) -> list[dict]:
    """Run validation across all client databases and report results."""
    conn = duckdb.connect(f"md:?custom_user_agent={PARTNER_USER_AGENT}")
    results = []
    for client in clients:
        result = validate_client_database(conn, client["database"])
        result["slug"] = client["slug"]
        results.append(result)
    conn.close()
    return results

Delivery Principles

• Prefer structural isolation over query-time tenant filtering for serious client work.
• Standardize the architecture, not the client data itself.
• Keep credentials and sharing boundaries explicit per client.
• Use a small set of approved deployment patterns rather than inventing a new one per engagement.

Public Product Anchors To Use

• Hypertenancy is the public MotherDuck pattern for dedicated compute per user or customer.
• MotherDuck documents service-account-driven provisioning and per-customer or per-workload isolation patterns for Hypertenancy-style applications.
• Read scaling is the public pattern for read-heavy BI and app workloads.
• Dives are shareable live workspace artifacts, and Embedded Dives can serve app surfaces when the client needs a read-only live dashboard inside an existing product. Keep implementation mechanics in motherduck-create-dive and REST endpoint details in motherduck-rest-api.
• DuckLake sharing is currently documented as read-only via shares in current DuckLake guidance.
• Shares are zero-copy and database-granularity, so partner delivery should publish curated database boundaries rather than exposing internal staging layouts.

Recommended Workflow

1. Classify the client pattern:

• internal analytics enablement
• customer-facing analytics
• pipeline and reporting
• regional or residency-constrained deployment

2. Pick the default architecture. 3. Standardize provisioning and deployment checklists. 4. Design the industry-specific data model, schema, and output assets for their use case.

Default Multi-Client Pattern

Use this as the default unless the client requirements force a deviation:

• one service account per client
• or one service account per workload boundary when the client has multiple blast-radius tiers
• one database namespace per client or stronger isolation boundary
• shared deployment checklist and provisioning steps
• per-client tokens and access revocation path

For customer-facing analytics with stronger isolation and performance requirements:

• pair this skill with motherduck-build-cfa-app
• use Hypertenancy-style patterns
• add read scaling only when concurrency demands it

What To Standardize

These are the architecture-level patterns that should be consistent across clients regardless of industry:

• connection pattern
• database provisioning and isolation model
• service account policy
• sharing model

Schemas, table structures, dashboard layouts, and Dive templates will vary by industry. Use motherduck-model-data to design the right schema for each client rather than forcing a single starter schema across all engagements.

When To Use Shares vs Dives vs Full Apps

• Use shares when the client team wants direct access to query data in MotherDuck or downstream tools.
• Use Dives when the client wants a live, shareable visualization inside the MotherDuck workspace.
• Use a full customer-facing app pattern when the client needs embedded analytics, product UX control, or stricter tenant-facing experience guarantees.

What To Keep Client-Specific

• schema design and table structure (driven by client industry and use case)
• source systems and ingestion sources
• business metrics
• data contracts
• residency constraints
• dashboard and Dive templates (tailored to the client's industry domain)
• end-user UX and rollout cadence

Region And Compliance Handling

• Verify current region availability before committing to a design.
• Keep client object storage, external buckets, and regional service-account assumptions aligned with the target MotherDuck region whenever the delivery pattern controls those choices.
• Escalate trust/compliance questions to motherduck-security-governance patterns when they become first-order blockers.
• Treat residency, AWS PrivateLink, and formal compliance documents as plan-sensitive and current-state-sensitive topics that require live verification.

The output of this skill should be a repeatable delivery pattern plus the client-specific exceptions that still need attention.