Skip to main content
skill CX Codex

schema-exploration — Claude Code skill: what it does, how to install

The schema-exploration skill for Claude Code analyzes an existing PostgreSQL database before writing queries or answering data questions.

Apache-2.0 113 installs ★ 1,886 updated 2026-10-22

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add timescale/pg-aiguide --skill schema-exploration -a claude-code
Open on GitHub

What schema-exploration does

The agent inspects metadata using read-only pg_catalog queries to locate relevant tables, views, triggers, routines, and extensions. Approval is required before checking data-derived statistics or rows. The workflow targets PostgreSQL 18, prohibiting schema modifications, role changes, and raw execution of untrusted functions.

Queries parameterize values using $1 and $2, avoiding raw identifier interpolation. The agent establishes scope, inspects structure, validates execution plans via EXPLAIN, and reports specific findings alongside limitations such as stale statistics or missing permissions.

What it helps with

  • explore an unfamiliar PostgreSQL database schema
  • locate specific tables, views, triggers, and extensions in the catalog
  • verify foreign keys, primary keys, and object dependencies
  • validate read-only queries with plain EXPLAIN plans

Example prompts for the agent

  • Explore the PostgreSQL database schema and find tables related to orders
  • Check the columns and foreign keys of the accounts table
  • Write a read-only query to count recent orders after checking the schema

How to install schema-exploration

1Skills CLI (Vercel)

npx skills add timescale/pg-aiguide --skill schema-exploration -a claude-code

2Manually: put the files in place

~/.claude/skills/schema-exploration/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/schema-exploration/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about schema-exploration

How to install schema-exploration in Claude Code?

Run npx skills add timescale/pg-aiguide --skill schema-exploration -a claude-code, then check ~/.claude/skills/schema-exploration/SKILL.md.

What does schema-exploration do?

It allows an AI agent to safely explore PostgreSQL database metadata and structure using read-only catalog queries.

What is required to run schema-exploration?

An active PostgreSQL database connection and user approval for inspecting data rows or statistics.

Source text

SKILL.md · Apache-2.0
---
name: schema-exploration
description: |
  Explore an existing PostgreSQL database before answering questions about its data or writing SQL. Use this skill whenever a user asks for a query or a data-backed answer against an unfamiliar schema (counts, missing or failed records, recent changes), asks where a business concept lives, or asks how tables, joins, views, routines, triggers, RLS, or extensions work. Find the relevant objects with read-only pg_catalog queries, then request approval before inspecting data-derived statistics or rows. Not a schema-design or migration guide.
license: Apache-2.0
metadata:
  author: tigerdata
---

# Explore a PostgreSQL database

Start with the user's question, not a full-database audit unless that is the explicit ask. Use the database connection already available to you; if none is available, ask for access or work from provided schema files. Stay within the database and schemas the user has authorized. Catalog metadata can reveal sensitive names or source code: do not export it unnecessarily.

## Workflow

1. Establish the current database, server version, role, and scope. Use [overview](references/overview.md) for a small inventory. Choose relevant schemas; do not assume `public` contains the application.
2. Pick the most promising object(s) and read **only** the matching drill-down reference: [tables](references/tables.md), [partitioning/inheritance](references/partitioning-and-inheritance.md), [foreign tables](references/foreign-tables.md), [views](references/views.md), [routines](references/routines.md), [triggers](references/triggers.md), [security/RLS](references/security.md), or [extensions](references/extensions.md). Follow cross-references only when the question requires them.
3. Corroborate meaning with comments, definitions, keys, and known dependencies. Names are clues, not proof of business meaning. If data-derived values would help, use [data-derived values](references/data-values.md) **only after obtaining approval** for the specific columns and access method. Ask the user when semantics remain ambiguous.
4. If the user wants SQL, follow [query authoring](references/query-authoring.md): establish join keys and grain, then validate a vetted read-only query with plain `EXPLAIN` where authorized. Do not mistake a valid plan for proof of business semantics.
5. Stop once you can answer. Report the specific schema-qualified objects and evidence, distinguish observations from inferences, and state limitations (permissions, stale statistics, missing dependencies, unknown application logic).

## Example finding

Illustrative only; report facts verified in the target database:

- **Observed:** `sales.orders` has a primary key on `order_id` and a foreign key from `account_id` to `sales.accounts.account_id`.
- **Inferred:** `sales.orders` likely records one row per order; the keys support this, but do not establish what the business calls an “order.”
- **Unresolved:** The catalog does not show whether canceled orders remain in this table. Confirm with the application owner before assuming they do.

## Safety and execution

- Prefer structural catalog queries; `pg_stats` is data-derived and requires approval too. Do not change schema, data, roles, or session-wide settings without authorization. Never call discovered functions or procedures, refresh materialized views, or run `EXPLAIN ANALYZE` on unknown queries. A function marked `STABLE` or `IMMUTABLE` is not a safety guarantee.
- If your client supports transactions, use a read-only transaction and a reasonable statement timeout for exploration. Metadata queries are not a license to run full-table counts or unrestricted scans. Ask before sampling data; sample only when necessary, with explicit limits and a clear understanding of table size and access controls.
- All reference queries are plain PostgreSQL SQL. Bind `$1`, `$2`, etc. as values using your client's API. `psql` users can follow the optional [psql adapter](references/psql.md). **Never interpolate an untrusted object name as raw SQL**; placeholders cannot replace SQL identifiers in data queries.
- Queries target PostgreSQL 18. Each version-sensitive section notes alternatives for older majors where applicable. Check `server_version_num` first. If a query fails due to permissions or version differences, report the limitation instead of guessing.

© tigerdata · Apache-2.0 · timescale/pg-aiguide

Similar skills

All skills for Data and databases →

From the same set11

The whole set →
design-postgres-tables design-postgres-tables — a reference skill for PostgreSQL table design: data types, indexes, constraints, JSONB and partitioning. Useful when your agent writes or edits a schema. CX Codex +1 680installs setup-timescaledb-hypertables setup-timescaledb-hypertables guides agents in designing TimescaleDB and Tiger Cloud hypertables for insert-heavy workloads. Helps configure chunk partitioning, columnstore compression, and sparse indexes. CX Codex +1 559installs find-hypertable-candidates find-hypertable-candidates reads a PostgreSQL schema and ranks which tables are worth converting to TimescaleDB hypertables. Useful before a migration. CX Codex +1 423installs postgres-hybrid-text-search postgres-hybrid-text-search teaches AI agents how to combine BM25 keyword matching with pgvector semantic retrieval using Reciprocal Rank Fusion in PostgreSQL. CX Codex +1 411installs design-postgis-tables design-postgis-tables is a Claude Code skill that covers PostGIS geometry types, coordinate systems, indexes and query patterns for designing schemas for location data. CX Codex +1 391installs migrate-postgres-tables-to-hypertables migrate-postgres-tables-to-hypertables plans the move of PostgreSQL tables to TimescaleDB hypertables: partition column, chunk interval, keys and compression. CX Codex +1 382installs postgres-database-migration The postgres-database-migration skill helps plan, test, and run PostgreSQL schema migrations safely. It is aimed at production tables and shared databases. CX Codex +1 285installs pg-aiguide pg-aiguide gives your coding agent semantic search over the PostgreSQL, TimescaleDB and PostGIS manuals plus curated Postgres best-practice skills. CX Codex +1 ★ 1,886repo stars

Project sponsors

Companies that keep this analytics open