diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e21a946 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,109 @@ +# 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](https://github.com/anthropics/skills). 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 + +```markdown +--- +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 + +1. Open an issue describing the skill you want to contribute +2. Agree on scope and deliverables +3. Submit a PR with the skill in `skills/your-skill-name/` +4. Reviewers (see [README contributors](README.md#contributors)) will review for accuracy and quality +5. Iterate, merge, get paid diff --git a/README.md b/README.md index d64fb5f..115acd6 100644 --- a/README.md +++ b/README.md @@ -41,18 +41,19 @@ Give every AI engineer instant access to the collected experience of a staff eng ## Contributors -**Stas Kelvich** — [REVIEWER] Cofounder of Neon and a long-time Postgres contributor. Deep experience with scaling and tuning Postgres for large production workloads. +- **[Stas Kelvich](https://github.com/kelvich)** — [REVIEWER] Cofounder of Neon and a long-time Postgres contributor. Deep experience with scaling and tuning Postgres for large production workloads. +- **[Jonathan Katz](https://github.com/jkatz)** — [REVIEWER] PostgreSQL Core Team member and Principal Product Manager at AWS (Amazon RDS). Active in the PostgreSQL community for over 15 years: co-chair of PGConf US, Secretary of the US PostgreSQL Association, and a contributor to pgvector. +- **[You]** - If you have experience scaling Postgres and would like to contribute, please [reach out](#call-for-contributors). -**Jonathan Katz** — [REVIEWER] PostgreSQL Core Team member and Principal Product Manager at AWS (Amazon RDS). Former VP of Platform Engineering at Crunchy Data. Active in the PostgreSQL community for over 15 years: co-chair of PGConf US, Secretary of the US PostgreSQL Association, and a contributor to pgvector. One of the most prolific writers and speakers on PostgreSQL fundamentals and best practices. ## Call for Contributors -We are looking for contributors with: +We are looking for skill contributors with: - Deep, proven experience helping a diverse set of applications build and scale on Postgres - A track record of writing clearly about Postgres (blog posts, documentation, conference talks) -All contributions are paid. Open an issue or reach out to start a conversation. +Skill contributions are paid. Open an issue or reach out to andy.hattemer@databricks.com if you're interested in contributing. ## AI Policy