← Explore all skills

DATABASES / Timescale

Postgres

Timescale's postgres skill from pg-aiguide: a dispatcher that sends the agent to nine reference guides for schema exploration, table design, pgvector and hybrid search, TimescaleDB hypertables and schema migrations.

“Use this skill for any PostgreSQL database work — table design, indexing, data types, constraints, extensions (pgvector, PostGIS, TimescaleDB), search, and migrations. …”

01 / THE REASONING

Why this made the selection.

  • Timescale publishes it in timescale/pg-aiguide (frontmatter license Apache-2.0, author tigerdata; NOTICE reads "Copyright 2025 Timescale, Inc., d/b/a Tiger Data"), and the README prints a single-skill install line for it: `npx skills add timescale/pg-aiguide --skill postgres`.
  • SKILL.md maps nine references to tasks, each ending in a bold line on when to use it (six begin "Use when", one "Use to" and two "Use for"): read-only schema exploration through pg_catalog, general and PostGIS table design, pgvector semantic search, BM25 plus pgvector hybrid search, hypertable setup, hypertable-candidate scoring, hypertable migration, and schema migrations.
  • The referenced guides carry explicit stop points: schema exploration asks for approval before reading data-derived statistics or rows, and the hypertable migration guide tells the agent to ask the user before changing a primary or unique key.

02 / THE REVIEW RECORD

What we actually inspected.

Source review has boundaries.
A clear record is more useful than a “safe” badge.

Material inspected

  • skills/postgres/SKILL.md (whole file)
  • README.md: usage routes, Agent Skills quickstart, MCP server, Claude Code plugin, licence
  • LICENSE
  • NOTICE
  • skills/schema-exploration/SKILL.md, the target of references/schema-exploration/guide.md
  • skills/migrate-postgres-tables-to-hypertables/SKILL.md: key changes, checklist, in-place and blue-green options
  • skills/postgres-hybrid-text-search/SKILL.md: frontmatter, pg_textsearch note, extension setup
  • skills/design-postgis-tables/SKILL.md: frontmatter
  • skills/postgres-database-migration/SKILL.md: drop-column and backfill examples, fork-based and dump-based testing
  • skills/pgvector-semantic-search/SKILL.md: frontmatter and core rules
  • skills/setup-timescaledb-hypertables/SKILL.md: frontmatter and retention policy step
  • skills/find-hypertable-candidates/SKILL.md: frontmatter
  • skills/schema-exploration/references/overview.md: version note
  • Repository tree at 187be00d: modes and targets of the entries under skills/postgres/references

Our findings

  • The frontmatter declares no allowed-tools; SKILL.md only tells the agent which reference file to load for which task.
  • Every entry under skills/postgres/references is a relative symbolic link (git mode 120000) into a sibling skill directory, for example design-postgres-tables.md -> ../../design-postgres-tables/SKILL.md and schema-exploration/guide.md -> ../../../schema-exploration/SKILL.md.
  • The README prints `npx skills add timescale/pg-aiguide --skill postgres` on a line of its own; the frontmatter name of skills/postgres/SKILL.md is postgres.
  • The schema-exploration guide works on the database connection already available to the agent and says not to change schema, data, roles or session-wide settings without authorization.

Not established by this review

  • Not executed: it was not installed or run.
  • Whether the skills installer copies the targets of the symbolic links under skills/postgres/references was not checked.
  • No SQL from any reference was run and no database was connected.
  • The public MCP endpoint at mcp.tigerdata.com was not called.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

Add a skill to your workflow.

Upstream setup instructions ↗

DOCUMENTED COMMAND

npx skills add timescale/pg-aiguide --skill postgres

Run in your terminal to choose your AI tools, project or global scope, and installation method. This short command follows the current upstream version; the review covers the revision shown above.

  1. Run the README's single-skill line `npx skills add timescale/pg-aiguide --skill postgres` in the target project; it selects the skill whose frontmatter name is postgres.
  2. The README's other lines install more: `npx skills add timescale/pg-aiguide` picks skills interactively, and `claude plugin marketplace add timescale/pg-aiguide` with `claude plugin install pg@aiguide` adds the Claude Code plugin.
  3. The README's MCP server at https://mcp.tigerdata.com/docs is a separate, optional addition for documentation search.

Before you start

  • A PostgreSQL connection available to the agent for the task, within the schemas the user has authorized
  • PostgreSQL 15+ for the six guides that declare it (PostGIS, pgvector, hybrid search and the three TimescaleDB guides); pg_textsearch needs PostgreSQL 17 or 18
  • pgvector, pg_textsearch, PostGIS or TimescaleDB only for the references that use them

04 / FOLLOW THE EVIDENCE

The source trail.

Our notes are separate from the original resource.
Check upstream before adopting a new version.

  1. https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/postgres/SKILL.md

    Supports: upstreamDescription, whySelected[0], whySelected[1], bestFor, access.permissions, install.steps[0], limitations[1], review.findings

  2. README.md at 187be00d ↗Checked

    https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/README.md

    Supports: install, compatibility, whySelected[0], limitations[5], limitations[6]

  3. https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/LICENSE

    Supports: license, limitations[6]

  4. NOTICE at 187be00d ↗Checked

    https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/NOTICE

    Supports: license, whySelected[0], limitations[6]

  5. https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/schema-exploration/SKILL.md

    Supports: whySelected[2], bestFor[0], access.permissions, install.prerequisites, limitations[2]

  6. https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/migrate-postgres-tables-to-hypertables/SKILL.md

    Supports: whySelected[2], bestFor[3], access.permissions, install.prerequisites, limitations[2], limitations[4]

  7. https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/postgres-hybrid-text-search/SKILL.md

    Supports: bestFor[2], access.permissions, access.cost, install.prerequisites, limitations[2], limitations[3]

  8. https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/design-postgis-tables/SKILL.md

    Supports: install.prerequisites, limitations[2]

  9. https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/postgres-database-migration/SKILL.md

    Supports: bestFor[4], access.permissions

  10. https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/pgvector-semantic-search/SKILL.md

    Supports: bestFor[2], access.permissions, install.prerequisites, limitations[2]

  11. https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/setup-timescaledb-hypertables/SKILL.md

    Supports: access.permissions, install.prerequisites, limitations[2]

  12. https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/find-hypertable-candidates/SKILL.md

    Supports: install.prerequisites, limitations[2]

  13. https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/schema-exploration/references/overview.md

    Supports: limitations[2]

Evidence & Ask