New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Schema Exploration

by timescale in timescale/pg-aiguide

Explore an existing PostgreSQL database before answering questions about its data or writing SQL.

Apache-2.0Auto-check passedDatabases

Install Schema Exploration

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

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install timescale/pg-aiguide schema-exploration --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/timescale/pg-aiguide.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/schema-exploration .claude/skills/schema-exploration && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
schema-exploration
GitHub stars
1.9k
Token cost
~1.1k tokens
SKILL.md length
478 words
Files
13 (incl. references)
Skills in repo
9
Repo updated
First seen
Licence
Apache-2.0

At a glance

Explore an existing PostgreSQL database before answering questions about its data or writing SQL.

  • Works in 5 steps: Establish the current database, server… → Pick the most promising object(s) and… → Corroborate meaning with comments,… → …
  • A user asks for a query
  • SKILL.md covers Workflow, Example finding and Safety and execution
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Schema Exploration is an agent skill from timescale/pg-aiguide. 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 pgcatalog queries, then request approval before inspecting data-derived statistics or rows. Not a…

Its SKILL.md is about 1.1k tokens, which your agent loads only when the skill is triggered. The skill folder holds 13 other files, including reference files (for example `references/data-values.md`, `references/extensions.md` and `references/foreign-tables.md`).

It sits in Databases, covering Code migrations, Database schema design and Statistics. It works with PostgreSQL, SQL and Model Context Protocol. The repository describes itself as: MCP server and Claude plugin for Postgres skills and documentation. Helps AI coding tools generate better PostgreSQL code. The licence is Apache-2.0.

When your agent uses it

  • A user asks for a query
  • A data-backed answer against an unfamiliar schema (counts
  • Recent changes)
  • Asks where a business concept lives

Example prompts

  • “/schema-exploration”

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

  1. Establish the current database, server version, role, and scope. Use overview for a small inventory. Choose relevant schemas; do not…
  2. Pick the most promising object(s) and read only the matching drill-down reference: tables, partitioning/inheritance, foreign tables…
  3. Corroborate meaning with comments, definitions, keys, and known dependencies. Names are clues, not proof of business meaning. If…
  4. If the user wants SQL, follow query authoring: establish join keys and grain, then validate a vetted read-only query with plain EXPLAIN…
  5. Stop once you can answer. Report the specific schema-qualified objects and evidence, distinguish observations from inferences, and state…

What it can do on your machine

Read from SKILL.md and the folder at commit 187be00. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Schema Exploration loads about 1.1k tokens when it runs, and up to ~13k if it reads all its reference files. Until then it costs about 140 tokens; SKILL.md has 478 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~140
When it runs · the whole SKILL.md, loaded when a task matches
~1.1k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~13k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from timescale/pg-aiguide at commit 187be00, republished under its Apache-2.0 licence (© timescale). 478 words, ~1,095 tokens.

Download SKILL.mdSave it as .claude/skills/schema-exploration/SKILL.md (or your agent's skills folder). This skill also uses 12 other files; get the full folder from GitHub.
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 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, partitioning/inheritance, foreign tables, views, routines, triggers, security/RLS, or extensions. 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 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: 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.
Show full SKILL.md (177 more words)Show less

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. 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.

© timescale, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 12 other files (references) in skills/schema-exploration of timescale/pg-aiguide.

  • SKILL.md
  • references/data-values.md
  • references/extensions.md
  • references/foreign-tables.md
  • references/overview.md
  • references/partitioning-and-inheritance.md
  • references/psql.md
  • references/query-authoring.md
  • references/routines.md
  • references/security.md
  • references/tables.md
  • references/triggers.md
  • references/views.md

Open the folder on GitHubat commit 187be00

Compare with similar skills

Schema Exploration next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Schema Exploration compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Schema Exploration this skilltimescale/pg-aiguide1.9k—~1.1kAutomated safety check: PassApache-2.0
NpgsqlrestNpgsqlRest/NpgsqlRest132—~7kAutomated safety check: NotesMIT
Database FundamentalsDanielPodolsky/ownyourcode2901 repos~1.6kAutomated safety check: PassMIT
Modelersidequery/sidemantic129—~4.2kAutomated safety check: PassApache-2.0
Golang Databaseunxed/f42412 repos~2.9kAutomated safety check: PassMIT
Postgressanjay3290/ai-skills4311 repos~975Automated safety check: PassApache-2.0

Similar skills

  • Npgsqlrest

    NpgsqlRest/NpgsqlRest

    Build and modify REST APIs with NpgsqlRest — exposing PostgreSQL as HTTP endpoints from two sources (database functions/procedures/tables/views, and plain .sql files), driven by SQL comment…

    132 GitHub stars~7k tokensUpdated 5 days ago
    DatabasesAuto-check: notes

  • Database Fundamentals

    DanielPodolsky/ownyourcode

    Reviews schema design, SQL queries, ORM patterns. An agent skill from DanielPodolsky/ownyourcode.

    290 GitHub starsUsed in 1 repo~1.6k tokens
    DatabasesAuto-check passed

  • Modeler

    sidequery/sidemantic

    Build, validate, and manage semantic models using Sidemantic.

    129 GitHub stars~4.2k tokensUpdated yesterday
    DatabasesAuto-check passed

  • Golang Database

    unxed/f4

    Comprehensive guide for Go database access — parameterized queries, struct scanning, NULLable columns, transactions, isolation levels, SELECT FOR UPDATE, connection pool, batch processing, context…

    241 GitHub starsUsed in 2 repos~2.9k tokens
    DatabasesAuto-check passed

  • Postgres

    sanjay3290/ai-skills

    Execute read-only SQL queries against multiple PostgreSQL databases.

    431 GitHub starsUsed in 1 repo~975 tokens
    DatabasesAuto-check passed

  • Semantic Analyst

    sidequery/sidemantic

    Answer analytical, KPI, metric, trend, cohort, and business-performance questions through a Sidemantic semantic layer.

    129 GitHub stars~982 tokensUpdated yesterday
    DatabasesAuto-check passed

More from timescale/pg-aiguide

All 9 skills in this repo

  • Find Hypertable Candidates

    timescale/pg-aiguide

    A skill your agent uses to analyze an existing PostgreSQL database and identify which tables should be converted to Timescale/TimescaleDB hypertables.

    1.9k GitHub starsUsed in 1 repo~2.6k tokens
    Auto-check passed

  • Pgvector Semantic Search

    timescale/pg-aiguide

    A skill your agent uses for setting up vector similarity search with pgvector for AI/ML embeddings, RAG applications, or semantic search.

    1.9k GitHub starsUsed in 1 repo~3.8k tokens
    Auto-check passed

  • Migrate Postgres Tables To Hypertables

    timescale/pg-aiguide

    A skill your agent uses to migrate identified PostgreSQL tables to Timescale/TimescaleDB hypertables with optimal configuration and validation.

    1.9k GitHub starsUsed in 1 repo~3.8k tokens
    Auto-check: warnings

  • Design Postgres Tables

    timescale/pg-aiguide

    A skill your agent uses for general PostgreSQL table design.

    1.9k GitHub stars~4.2k tokensUpdated yesterday
    Auto-check passed

  • Postgres Hybrid Text Search

    timescale/pg-aiguide

    A skill your agent uses to implement hybrid search combining BM25 keyword search with semantic vector search using Reciprocal Rank Fusion (RRF).

    1.9k GitHub stars~3.1k tokensUpdated yesterday
    Auto-check passed

  • Setup Timescaledb Hypertables

    timescale/pg-aiguide

    A skill your agent uses when creating database schemas or tables for Timescale, TimescaleDB, TigerData, or Tiger Cloud, especially for time-series, IoT, metrics, events, or log data.

    1.9k GitHub stars~4.7k tokensUpdated yesterday
    Auto-check passed

Works with

Categories

Questions about Schema Exploration

What does Schema Exploration do?

Explore an existing PostgreSQL database before answering questions about its data or writing SQL. Schema Exploration is an agent skill from timescale/pg-aiguide. Explore an existing PostgreSQL database before answering questions about its data or writing SQL.

When should I use Schema Exploration?

Schema Exploration fits situations like: A user asks for a query; A data-backed answer against an unfamiliar schema (counts; recent changes); asks where a business concept lives.

How do I install Schema Exploration in Claude Code?

Run `npx skills add timescale/pg-aiguide --skill schema-exploration -a claude-code`. Or copy the skill folder (skills/schema-exploration in timescale/pg-aiguide) into .claude/skills/schema-exploration in your project. Claude Code loads it when a task matches its description.

How do I install Schema Exploration in Codex?

Run `npx skills add timescale/pg-aiguide --skill schema-exploration -a codex`. Or copy the skill folder (skills/schema-exploration in timescale/pg-aiguide) into .agents/skills/schema-exploration in your project. Codex loads it when a task matches its description.

Can I use Schema Exploration in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add timescale/pg-aiguide --skill schema-exploration -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/schema-exploration, .gemini/skills/schema-exploration, .github/skills/schema-exploration and .opencode/skills/schema-exploration in your project.

What does Schema Exploration need to run?

SKILL.md names no scripts, command-line tools or credentials: Schema Exploration is instructions for the agent only.

Does Schema Exploration access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Schema Exploration safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Schema Exploration use?

Schema Exploration is published under the Apache-2.0 licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Schema Exploration use?

About 1.1k tokens (SKILL.md is roughly 4.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 12k tokens, read only when the agent opens those files.

What are the alternatives to Schema Exploration?

Skills that share tags, products or a category with Schema Exploration: Npgsqlrest (NpgsqlRest/NpgsqlRest, 132 stars), Database Fundamentals (DanielPodolsky/ownyourcode, 290 stars), Modeler (sidequery/sidemantic, 129 stars) and Golang Database (unxed/f4, 241 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Schema Exploration?

timescale (a GitHub organization) maintains it in timescale/pg-aiguide, which has 1,859 GitHub stars. The repository holds 9 skills in this directory. The repository was last updated on October 7, 2026.

Source: timescale/pg-aiguide on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.