mirror of
https://github.com/neondatabase/postgres-skills.git
synced 2026-09-11 19:46:49 +03:00
110 lines
4.0 KiB
Markdown
110 lines
4.0 KiB
Markdown
# 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
|