How to Create Claude Skills That Interact With Databases Like PostgreSQL or Supabase

Claude Skills enable AI agents to execute SQL queries, manage schemas, and invoke edge functions in PostgreSQL and Supabase through declarative SKILL.md configurations and the Model Context Protocol (MCP) gateway, eliminating the need for custom database connection code.

The ComposioHQ/awesome-claude-skills repository provides production-ready integrations that transform Claude into a database administrator. By leveraging the Connect skill for generic PostgreSQL access and the Supabase Automation skill for cloud-native workflows, you can create Claude Skills that interact with databases using only natural language prompts and environment variable configuration.

Architecture of Database-Enabled Claude Skills

Every database skill in the repository follows a standardized structure that separates configuration from implementation.

The required folder layout is:

skill-folder/
├── SKILL.md          # YAML front-matter + step-by-step instructions

├── scripts/          # Helper scripts (Python, TypeScript, etc.)

└── resources/        # Reference files (SQL schemas, API docs)

When Claude loads a skill, it reads the SKILL.md metadata to discover the required MCP server endpoint. For database interactions, Claude routes requests through the MCP gateway, which securely forwards calls to the target database using native drivers (ODBC for PostgreSQL or the Supabase client SDK) without exposing connection strings to the LLM context.

The execution flow requires four components:

1. Composio API key stored in the COMPOSIO_API_KEY environment variable.
2. Session creation via composio.create(user_id), which provisions an MCP endpoint at session.mcp.url.
3. Tool registration, where the skill maps natural language commands to specific tool slugs like POSTGRESQL_EXECUTE_QUERY.
4. Runtime orchestration, where Claude translates user prompts into parameterized database calls.

Querying PostgreSQL With the Connect Skill

The connect/SKILL.md file defines the core integration for PostgreSQL access, exposing the POSTGRESQL_EXECUTE_QUERY tool slug that Claude uses to execute arbitrary SQL.

Configuring the MCP Gateway

First, initialize a Composio session and configure the Claude client to route database requests through the MCP gateway:

import os
from composio import Composio
from claude_agent_sdk.client import ClaudeSDKClient
from claude_agent_sdk.types import ClaudeAgentOptions

# Initialize Composio with your API key

composio = Composio(api_key=os.getenv("COMPOSIO_API_KEY"))
session = composio.create(user_id="demo_user")

# Configure MCP server endpoint

options = ClaudeAgentOptions(
    system_prompt="You can run SQL queries against PostgreSQL databases.",
    mcp_servers={
        "composio": {
            "type": "http",
            "url": session.mcp.url,
            "headers": {"x-api-key": os.getenv("COMPOSIO_API_KEY")},
        }
    },
)

# Execute query through Claude

async with ClaudeSDKClient(options) as client:
    response = await client.query(
        "Run SQL on my_postgres: SELECT id, name FROM users WHERE active = true;"
    )
    print(response)  # Returns JSON array of active users

Key implementation detail: According to connect/SKILL.md, the skill template automatically substitutes the tool slug POSTGRESQL_EXECUTE_QUERY with the user-provided SQL, handling connection pooling and result serialization through the MCP layer.

Managing Supabase Data and Edge Functions

The supabase-automation/ directory contains a specialized skill that wraps Supabase’s REST and GraphQL APIs, enabling Claude to perform SQL queries, schema introspection, and edge-function invocations.

Querying Tables and Invoking Edge Functions

The Supabase skill extends beyond raw SQL to include platform-specific operations. The supabase-automation/SKILL.md enumerates supported commands for database tables and serverless functions.

import os
from composio import Composio
from claude_agent_sdk.client import ClaudeSDKClient
from claude_agent_sdk.types import ClaudeAgentOptions

composio = Composio(api_key=os.getenv("COMPOSIO_API_KEY"))
session = composio.create(user_id="demo_user")

options = ClaudeAgentOptions(
    system_prompt="You can query Supabase databases and call its edge functions.",
    mcp_servers={
        "composio": {
            "type": "http",
            "url": session.mcp.url,
            "headers": {"x-api-key": os.getenv("COMPOSIO_API_KEY")},
        }
    },
)

async with ClaudeSDKClient(options) as client:
    # Read rows from a Supabase table

    resp = await client.query(
        "Supabase: SELECT * FROM public.orders WHERE status = 'pending';"
    )
    print(resp)
    
    # Invoke a Supabase Edge Function with JSON payload

    resp = await client.query(
        "Supabase Edge Function `calculate_totals`: {\"order_id\": 42}"
    )
    print(resp)

Implementation note: As referenced in the repository README, the Supabase Automation skill bundles the necessary client SDK calls, allowing Claude to handle authentication and request formatting automatically.

Creating Custom Database Skills

For specialized workflows—such as transaction-heavy operations or analytics-specific querying—you can extend the base patterns using the skill-creator/SKILL.md template.

Defining the SKILL.md Template

Create a new directory structure:

my-pg-skill/
├── SKILL.md
└── scripts/
    └── pg_helper.py

Populate SKILL.md with metadata and instructions:

---
name: pg-analytics
description: Run analytics-style queries on PostgreSQL and return summarized results.
---

# PG Analytics Skill

## When to Use This Skill

- Generate KPI dashboards
- Perform ad-hoc data exploration
- Export query results to CSV

## Instructions

1. Use the tool `POSTGRESQL_EXECUTE_QUERY` with the SQL you want to run.
2. If the result set has more than 100 rows, paginate using OFFSET and LIMIT.
3. For numeric columns, compute AVG, SUM, and COUNT automatically.

## Examples

- **Prompt:** "Give me the total sales per month for the last quarter."
- **Claude Action:** `Run SQL on my_postgres:
  SELECT DATE_TRUNC('month', order_date) AS month,
         SUM(amount) AS total_sales
   FROM orders
   WHERE order_date >= CURRENT_DATE - INTERVAL '3 months'
   GROUP BY month;`

Pattern guidance: Place helper utilities in scripts/pg_helper.py to expose convenience functions (e.g., paginate(), summarize()) that Claude can invoke through the MCP server when the standard tool slugs do not provide sufficient granularity.

Summary

• Declarative configuration via SKILL.md files in directories like connect/ and supabase-automation/ eliminates boilerplate database connection code.
• PostgreSQL integration uses the POSTGRESQL_EXECUTE_QUERY tool slug defined in connect/SKILL.md to execute arbitrary SQL through the MCP gateway.
• Supabase workflows leverage the supabase-automation/ skill to combine SQL operations with edge-function invocations and storage management.
• Security model relies on the Composio MCP server to handle credentials, ensuring database connection strings never enter the Claude context window.
• Extensibility follows the template in skill-creator/SKILL.md, allowing custom skills for analytics, ETL, or schema migration tasks.

Frequently Asked Questions

What is the MCP gateway in Claude Skills?

The Model Context Protocol (MCP) gateway is the HTTP endpoint (exposed at session.mcp.url when you call composio.create()) that Claude uses to communicate with external tools. For database skills, this gateway acts as a secure proxy, receiving SQL queries from Claude and forwarding them to PostgreSQL or Supabase using the native client libraries, then returning structured results to the LLM.

Do I need to write SQL queries manually when using these skills?

No. While you can provide explicit SQL in your prompts, the skill architecture allows Claude to generate queries based on natural language requests. The SKILL.md files in supabase-automation/ and connect/ provide Claude with schema context and table relationships, enabling it to construct valid SQL automatically while you review the generated statements before execution.

Can I use these skills with databases other than PostgreSQL and Supabase?

Yes. The Connect skill supports over 1,000 integrations beyond PostgreSQL, including MySQL, MongoDB, and cloud data warehouses. The pattern remains identical: configure the MCP gateway, reference the appropriate tool slug for the target database (as defined in the respective SKILL.md), and prompt Claude with natural language commands. The Composio platform handles the protocol translation.

How secure is the database connection through Composio?

The connection uses token-based authentication via the COMPOSIO_API_KEY and short-lived session tokens. Database credentials are stored in the Composio infrastructure and injected at the MCP server layer, never exposed to Claude's context window or prompt history. All traffic to session.mcp.url uses HTTPS, and the ODBC drivers or Supabase SDK connections originate from Composio's managed environment rather than the client code.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}