design-postgis-tables

Comprehensive PostGIS spatial table design reference covering geometry types, coordinate systems, spatial indexing, and performance patterns for location-based applications

Quality

73%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/design-postgis-tables/SKILL.md

Quality

Content

76%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 content is a highly actionable, well-structured PostGIS reference with executable SQL for the common table-design cases, though it reads as a reference rather than a sequenced workflow with validation checkpoints. Tightening the repeated injection note and splitting some catalogs into reference files would improve conciseness and progressive disclosure.

Suggestions

Add an explicit design workflow with validation checkpoints, e.g. '1. Answer the 5 questions -> 2. Pick geometry/geography + SRID -> 3. Add CHECK(ST_IsValid) constraint -> 4. Create GiST index -> 5. EXPLAIN ANALYZE to verify index use.'

De-duplicate the SQL-injection guidance (it appears both in the intro note and Common Pitfalls #6); keep it in one canonical place.

Move the SRID range table and full geometry-type catalog into a separate references/ file referenced one level deep, keeping SKILL.md as a lean overview.

Dimension	Reasoning	Score
Conciseness	The body is mostly tables, decision lists, and executable SQL that earn their tokens, with only minor redundancy (the SQL-injection note is repeated verbatim in Common Pitfalls #6); it is efficient but could be trimmed slightly, matching the anchor for minor instances of over-explanation.	4 / 5
Actionability	It provides copy-paste-ready CREATE TABLE / CREATE INDEX / query examples across the common cases (POI, parcels, GPS tracks, service zones) plus concrete performance and validation patterns, matching the anchor for fully executable, comprehensive guidance.	5 / 5
Workflow Clarity	The 'Before You Start (5 Questions)' and 'Core Rules' give an implicit design sequence, but there is no explicit ordered workflow with validation checkpoints (e.g., validate geometry -> fix -> re-validate -> index), so it sits at the anchor for steps present but checkpoints missing.	3 / 5
Progressive Disclosure	No bundle files exist and all content lives in one well-sectioned SKILL.md with clear headers and tables; for a file this long, detailed catalogs (e.g., the SRID range table, full geometry-type catalog) could be split into one-level-deep reference files, leaving it just short of the clear-overview-with-references anchor at 5.	4 / 5
	Total	16 / 20 Passed

Description

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

The description is specific and clearly distinct within the PostGIS niche, but it omits any explicit 'when to use' trigger guidance, which limits its completeness. Adding a 'Use when...' clause with natural trigger phrases would raise its score.

Suggestions

Add an explicit 'Use when...' clause, e.g. 'Use when designing PostGIS spatial tables, choosing geometry vs geography, or planning spatial indexes for location-based applications.'

Include natural trigger synonyms users say (GIS, GPS, latitude/longitude, SRID) to broaden keyword coverage.

Reframe 'reference covering ...' as concrete actions ('Design and create PostGIS spatial tables, choose geometry types, ...') to push specificity toward 5.

Dimension	Reasoning	Score
Specificity	The description names several concrete coverage areas ('geometry types, coordinate systems, spatial indexing, and performance patterns'), matching the anchor for listing several specific actions with minor gaps; it stops short of the comprehensive, multi-action list that defines a 5.	4 / 5
Completeness	It clearly states what the skill is (a PostGIS spatial table design reference) but provides no 'Use when...' clause or equivalent trigger guidance; per the rubric, a missing explicit trigger clause caps completeness at 3.	3 / 5
Trigger Term Quality	It includes natural terms a PostGIS user would say ('PostGIS', 'spatial', 'geometry', 'coordinate systems', 'location-based'), but misses common synonyms a user might voice such as GIS, latitude/longitude, SRID, or GPS, so it sits at good-but-incomplete keyword coverage.	4 / 5
Distinctiveness Conflict Risk	'Comprehensive PostGIS spatial table design reference' carves out a clear, narrow niche with distinct triggers and minimal overlap risk with other skills.	5 / 5
	Total	16 / 20 Passed

Validation

93%

Warnings & errors only

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

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
metadata_version	'metadata.version' is missing	Warning

	Total	15 / 16 Passed

Repository: timescale/pg-aiguide
Path: skills/design-postgis-tables/SKILL.md
Commit: 2bf9f11

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

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.