Contributing to `postgres-skills`

Thank you for your interest in contributing. This project curates Postgres knowledge from practitioners with real production experience. Contributions are paid.

To discuss a contribution, open an issue or email andy.hattemer@databricks.com.

What We're Looking For

Skills that encode knowledge an experienced Postgres engineer carries in their head but that an AI does not reliably have on its own: subtle tradeoffs, failure patterns, guidelines that depend on context, lessons learned from real systems.

Good candidates:

Schema and data modeling patterns for common application domains
Indexing strategies and when each applies
Query optimization techniques with concrete examples
Migration patterns and pitfalls
Connection pooling and concurrency gotchas
Common mistakes and how to avoid them

If the information is already in the Postgres docs or widely covered in generic tutorials, it is probably not worth encoding as a skill.

AI Policy

Skills must be written by humans. AI-generated content defeats the purpose. If the information can be generated by an AI on demand, there is no value in encoding it into a skill ahead of time. The value of a skill comes from human judgment and accumulated experience that AI does not already have.

AI tools may be used for reviewing and testing skill content, but not for authoring it.

Skill Format

Skills follow the Agent Skills open standard. Here is the required structure:

skills/your-skill-name/
├── SKILL.md              # Required: frontmatter + instructions
├── references/           # Optional: detailed reference docs loaded on demand
├── scripts/              # Optional: helper scripts
└── assets/               # Optional: templates, data files (not loaded into context)

The directory name must match the name field in the frontmatter.

SKILL.md

---
name: your-skill-name          # lowercase, hyphens only, 1-64 chars
description: |
  What this skill covers and when an agent should use it. Include
  keywords that match how engineers describe the tasks this skill helps
  with. 1-1024 chars.
---

# Your Skill Title

Body content here. Write for an AI agent: step-by-step guidance,
concrete examples, non-obvious tradeoffs. Imperative form. Under 500
lines. Move detailed reference material to references/.

Description tips:

Describe both capability and when to invoke: "Use when designing tables, choosing data types, or normalizing a schema."
Include keywords engineers use when asking about these topics
Keep it specific enough to avoid triggering on unrelated tasks

Body tips:

Write for an AI agent, not a human reader
Include the non-obvious things: edge cases, tradeoffs, things that commonly go wrong
Keep the body under 500 lines; move reference material to references/
Use imperative form: "Prefer BIGINT over INT for primary keys", not "You should prefer..."
Concrete beats abstract: include SQL examples

references/ files

Load-on-demand documentation. Use for:

Detailed API or syntax references
Domain-specific deep dives
Content that is only relevant for a subset of tasks the skill covers

Keep individual files focused. Aim for ~100 lines per file; add a table of contents for longer files.

Quality Bar

Before submitting, check:

The skill encodes knowledge an AI would not already have
Content is based on real experience, not restated documentation
SQL examples are correct and runnable
SKILL.md body is under 500 lines
Frontmatter name matches the directory name
Description specifies both what the skill covers and when to use it
No AI-generated content

Process

Open an issue describing the skill you want to contribute
Agree on scope and deliverables
Submit a PR with the skill in skills/your-skill-name/
Reviewers (see README contributors) will review for accuracy and quality
Iterate, merge, get paid

4.0 KiB Raw Blame History

Contributing to postgres-skills