first commit

2026-03-02 21:16:26 +01:00
commit 841f43285e
179 changed files with 33193 additions and 0 deletions
--- a/.agents/skills/supabase-postgres-best-practices/README.md
+++ b/.agents/skills/supabase-postgres-best-practices/README.md
@@ -0,0 +1,116 @@
+# Supabase Postgres Best Practices - Contributor Guide
+
+This skill contains Postgres performance optimization references optimized for
+AI agents and LLMs. It follows the [Agent Skills Open Standard](https://agentskills.io/).
+
+## Quick Start
+
+```bash
+# From repository root
+npm install
+
+# Validate existing references
+npm run validate
+
+# Build AGENTS.md
+npm run build
+```
+
+## Creating a New Reference
+
+1. **Choose a section prefix** based on the category:
+   - `query-` Query Performance (CRITICAL)
+   - `conn-` Connection Management (CRITICAL)
+   - `security-` Security & RLS (CRITICAL)
+   - `schema-` Schema Design (HIGH)
+   - `lock-` Concurrency & Locking (MEDIUM-HIGH)
+   - `data-` Data Access Patterns (MEDIUM)
+   - `monitor-` Monitoring & Diagnostics (LOW-MEDIUM)
+   - `advanced-` Advanced Features (LOW)
+
+2. **Copy the template**:
+   ```bash
+   cp references/_template.md references/query-your-reference-name.md
+   ```
+
+3. **Fill in the content** following the template structure
+
+4. **Validate and build**:
+   ```bash
+   npm run validate
+   npm run build
+   ```
+
+5. **Review** the generated `AGENTS.md`
+
+## Skill Structure
+
+```
+skills/supabase-postgres-best-practices/
+├── SKILL.md           # Agent-facing skill manifest (Agent Skills spec)
+├── AGENTS.md          # [GENERATED] Compiled references document
+├── README.md          # This file
+└── references/
+    ├── _template.md      # Reference template
+    ├── _sections.md      # Section definitions
+    ├── _contributing.md  # Writing guidelines
+    └── *.md              # Individual references
+
+packages/skills-build/
+├── src/               # Generic build system source
+└── package.json       # NPM scripts
+```
+
+## Reference File Structure
+
+See `references/_template.md` for the complete template. Key elements:
+
+````markdown
+---
+title: Clear, Action-Oriented Title
+impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
+impactDescription: Quantified benefit (e.g., "10-100x faster")
+tags: relevant, keywords
+---
+
+## [Title]
+
+[1-2 sentence explanation]
+
+**Incorrect (description):**
+
+```sql
+-- Comment explaining what's wrong
+[Bad SQL example]
+```
+````
+
+**Correct (description):**
+
+```sql
+-- Comment explaining why this is better
+[Good SQL example]
+```
+
+```
+## Writing Guidelines
+
+See `references/_contributing.md` for detailed guidelines. Key principles:
+
+1. **Show concrete transformations** - "Change X to Y", not abstract advice
+2. **Error-first structure** - Show the problem before the solution
+3. **Quantify impact** - Include specific metrics (10x faster, 50% smaller)
+4. **Self-contained examples** - Complete, runnable SQL
+5. **Semantic naming** - Use meaningful names (users, email), not (table1, col1)
+
+## Impact Levels
+
+| Level | Improvement | Examples |
+|-------|-------------|----------|
+| CRITICAL | 10-100x | Missing indexes, connection exhaustion |
+| HIGH | 5-20x | Wrong index types, poor partitioning |
+| MEDIUM-HIGH | 2-5x | N+1 queries, RLS optimization |
+| MEDIUM | 1.5-3x | Redundant indexes, stale statistics |
+| LOW-MEDIUM | 1.2-2x | VACUUM tuning, config tweaks |
+| LOW | Incremental | Advanced patterns, edge cases |
+```