Name: querying-local-postgres
Rating: 68.8 (1 reviews)
Author: PostHog

querying-local-postgres

Run read-only SQL against the local Postgres app database (SELECT, EXPLAIN, EXPLAIN ANALYZE on SELECT). Default local URL postgres://posthog:posthog@localhost:5432/posthog; else DATABASE_URL. Use when querying the local DB, inspecting tables, debugging data, or analyzing query plans. Mutations are strictly forbidden.

Quality

83%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

High

Do not use without reviewing

Quality

Content

75%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 highly actionable with executable command patterns and a clear, safety-checked workflow for read-only DB queries. Its main weakness is conciseness, where a few concept-heavy explanation blocks (notably the PGOPTIONS rationale) could be trimmed.

Suggestions

Condense the PGOPTIONS-vs-SET-SESSION-CHARACTERISTICS rationale into a one-line note; the full transaction-semantics explainer is concept-heavy and assumes Claude lacks Postgres knowledge it has.

Tighten the connection/DATABASE_URL section by collapsing the multiple env-file scenarios into a short decision table or a single canonical command with brief variants.

Add an explicit error-recovery step to the workflow (e.g., 'If psql errors, re-read the message, adjust the SQL, and re-run') to turn the clear sequence into a full feedback loop.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient and assumes SQL/psql knowledge, but the multi-paragraph PGOPTIONS-vs-SET-SESSION rationale and the lengthy multi-scenario connection/env section add unnecessary explanation that could be tightened.	3 / 5
Actionability	Provides multiple copy-paste-ready command patterns (hardcoded URL, DATABASE_URL in shell, dotenv variant) plus concrete flags (ON_ERROR_STOP=1, -x, LIMIT 100), covering the common cases fully.	5 / 5
Workflow Clarity	A clear numbered sequence (forbid mutations, translate, show SQL, run, interpret) with explicit safety checkpoints (read-only PGOPTIONS, show-before-run, refuse-writes gate); lacks an explicit error-recovery feedback loop, keeping it just below the top anchor.	4 / 5
Progressive Disclosure	Well-organized into focused sections with one-level-deep pointers to repo files; no bundle files exist so content is appropriately inline, though the dense connection/env section could be split out for cleaner navigation.	4 / 5
	Total	16 / 20 Passed

Description

92%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 concrete, complete, and distinctive, clearly stating both what the skill does and when to use it with natural trigger phrases. Its only minor gap is missing a few synonyms (e.g., psql, .sql) that would round out trigger-term coverage.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions (SELECT, EXPLAIN, EXPLAIN ANALYZE, inspecting tables, debugging, query plans) with comprehensive coverage and named SQL statement types, matching the top anchor.	5 / 5
Completeness	Explicitly states what ('Run read-only SQL against the local Postgres app database') and when ('Use when querying the local DB, inspecting tables, debugging data, or analyzing query plans') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Includes natural phrases users would say ('querying the local DB', 'inspecting tables', 'debugging data', 'analyzing query plans') but misses some synonyms and terms like 'psql' or '.sql', so it falls just below comprehensive.	4 / 5
Distinctiveness Conflict Risk	Carves a clear niche (read-only queries against the local Postgres app DB) with explicit read-only/mutation constraints that distinguish it from general DB or migration skills, minimizing conflict risk.	5 / 5
	Total	19 / 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
relative_links	Relative link issues: 1 suspicious	Warning

	Total	15 / 16 Passed

Repository: PostHog/posthog
Path: .agents/skills/querying-local-postgres/SKILL.md
Commit: 6fca5f8

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.