docs: update readme add contributing.md

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

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