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.
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.
- 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.
- 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.
- 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.
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
- README.md at 187be00d ↗Checked
https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/README.md
Supports: install, compatibility, whySelected[0], limitations[5], limitations[6]
https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/LICENSE
Supports: license, limitations[6]
- NOTICE at 187be00d ↗Checked
https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/NOTICE
Supports: license, whySelected[0], limitations[6]
https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/schema-exploration/SKILL.md
Supports: whySelected[2], bestFor[0], access.permissions, install.prerequisites, limitations[2]
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]
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]
https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/design-postgis-tables/SKILL.md
Supports: install.prerequisites, limitations[2]
https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/postgres-database-migration/SKILL.md
Supports: bestFor[4], access.permissions
https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/pgvector-semantic-search/SKILL.md
Supports: bestFor[2], access.permissions, install.prerequisites, limitations[2]
https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/setup-timescaledb-hypertables/SKILL.md
Supports: access.permissions, install.prerequisites, limitations[2]
https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/find-hypertable-candidates/SKILL.md
Supports: install.prerequisites, limitations[2]
https://github.com/timescale/pg-aiguide/blob/187be00d317a51210c132010d947f4546ffb5eef/skills/schema-exploration/references/overview.md
Supports: limitations[2]