# 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