CtrlK
BlogDocsLog inGet started
Tessl Logo

postgres

Use this skill for any PostgreSQL database work — table design, indexing, data types, constraints, extensions (pgvector, PostGIS, TimescaleDB), search, and migrations. **Trigger when user asks to:** - Explore an existing PostgreSQL database to understand its objects and relationships - Design or modify PostgreSQL tables, schemas, or data models - Choose data types, constraints, indexes, or partitioning strategies - Work with pgvector embeddings, semantic search, or RAG - Set up full-text search, hybrid search, or BM25 ranking - Use PostGIS for spatial/geographic data - Set up TimescaleDB hypertables for time-series data - Migrate tables to hypertables or evaluate migration candidates - Plan or execute safe schema migrations with zero downtime **Keywords:** PostgreSQL, Postgres, SQL, schema, table design, indexes, constraints, pgvector, PostGIS, TimescaleDB, hypertable, semantic search, hybrid search, BM25, time-series, migration

71

Quality

89%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

88%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is a clean, well-organized index that routes to nine clearly-signaled one-level-deep references with no padding — exactly the SKILL.md-as-overview pattern. It falls just short of top marks on actionability (no inline quick-start snippet) and progressive disclosure (orphaned reference files and a nested references/ directory under schema-exploration).

Suggestions

Add a short inline quick-start snippet (e.g., a basic CREATE TABLE with a sensible index) for the most common task so simple requests don't require opening a reference file.

Either link the orphaned files (backfill-strategies.md, complete-example.md, validation-queries.md) from SKILL.md or remove them from the bundle so all content is discoverable.

Flatten or remove the nested references/ directory inside references/schema-exploration/ so every path from SKILL.md stays one level deep.

DimensionReasoningScore

Conciseness

The ~30-line body is a pure index: each entry is one line of scope ("Data types, constraints, indexes, JSONB patterns, partitioning, and PostgreSQL best practices") plus a bolded use-when pointer, with zero explanation of concepts Claude already knows. This matches the lean 'every token earns its place' anchor; nothing to trim.

5 / 5

Actionability

The body is an instruction-only router and its guidance is concrete: real paths ("references/design-postgres-tables.md"), per-reference scopes, and a bolded directive per entry ("Use for any general table/schema design task"). Not a 5 because there is no inline quick-start example for the most common task (e.g., a basic CREATE TABLE / index pattern), so a user must always open a reference file before acting — 'minor gaps' at anchor 4.

4 / 5

Workflow Clarity

"How to Use" gives an unambiguous three-step sequence: "1. Identify which reference matches the user's task... 2. Load the reference file... 3. For tasks spanning multiple areas..., load multiple references as needed." This is a single-purpose routing skill with no risky operations, so the simple-skill exception applies and the single action is unambiguous. A 4 would require missing checkpoints, but none are needed for non-destructive reference loading.

5 / 5

Progressive Disclosure

All nine referenced paths resolve to real files one level deep, grouped under clear category sections with per-reference use-when signals — close to the anchor-5 pattern. Not a 5 because the actual bundle has minor organization gaps: three reference files (backfill-strategies.md, complete-example.md, validation-queries.md) are not navigable from SKILL.md, and references/schema-exploration/ contains a further nested references/ directory, introducing 2-level depth for that entry.

4 / 5

Total

18

/

20

Passed

Description

88%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description: it states the full capability surface concretely, gives an explicit multi-line trigger list, and includes a keyword line with synonyms. The only weaknesses are a few missing natural trigger terms (e.g., database design, query optimization) and slight generic-keyword overlap risk from 'SQL' and 'schema'.

Suggestions

Add natural user phrasings to the keyword line such as 'database design', 'query optimization', 'performance tuning', and 'SQL queries' to broaden natural-language trigger coverage.

Qualify the generic keywords 'SQL' and 'schema' with PostgreSQL context (e.g., 'PostgreSQL schema', 'Postgres SQL') to reduce overlap with generic SQL/database skills.

DimensionReasoningScore

Specificity

The description lists many concrete actions — "Explore an existing PostgreSQL database", "Design or modify PostgreSQL tables, schemas, or data models", "Choose data types, constraints, indexes, or partitioning strategies", "Set up TimescaleDB hypertables", "Plan or execute safe schema migrations with zero downtime" — covering the full domain comprehensively. Not a level below because 4 allows 'minor gaps in coverage' and no significant capability area is missing.

5 / 5

Completeness

It explicitly answers both questions: what ("Use this skill for any PostgreSQL database work — table design, indexing, data types, constraints, extensions..., search, and migrations") and when ("**Trigger when user asks to:**" followed by nine concrete trigger phrases). This is the anchor-5 pattern of a clear 'what' plus explicit 'Use when' triggers; a 4 would require the 'when' to be less explicit, which it is not.

5 / 5

Trigger Term Quality

The keyword list ("PostgreSQL, Postgres, SQL, schema, table design, indexes, constraints, pgvector, PostGIS, TimescaleDB, hypertable, semantic search, hybrid search, BM25, time-series, migration") includes the natural Postgres/PostgreSQL synonym and most terms a user would say. Not a 5 because common natural phrasings such as "database design", "query optimization / performance tuning", "vacuum", or "SQL queries" are absent, which is the 'a few natural terms missing' anchor.

4 / 5

Distinctiveness Conflict Risk

Highly specific niche markers ("pgvector", "PostGIS", "TimescaleDB", "hypertable", "BM25") make this mostly distinct with minimal conflict risk against unrelated skills. Not a 5 because generic keywords like "SQL", "schema", and "migration" create minor overlap risk with generic SQL/non-Postgres database skills — the anchor-4 'minor overlap risk with closely related skills' case.

4 / 5

Total

18

/

20

Passed

Validation

81%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 13 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

metadata_version

'metadata.version' is missing

Warning

relative_links

Relative link issues: 1 deeper-than-1-level

Warning

referenced_paths_exist

Referenced path issues: 1 deeper-than-1-level

Warning

Total

13

/

16

Passed

Repository
timescale/pg-aiguide
Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.