templates for skills

skills/using-supabase/AGENTS.md

@@ -0,0 +1,53 @@
+# Using Supabase
+
+**Version 1.0.0**
+Supabase
+January 2026
+
+> This document is optimized for AI agents and LLMs. Rules are prioritized by performance impact.
+
+---
+
+## Abstract
+
+Comprehensive Supabase development guide covering Auth, Storage, Edge Functions, Realtime, CLI, supabase-js SDK, and MCP integration.
+
+---
+
+## Table of Contents
+
+1. [TODO Section](#todo-section) - **TODO**
+
+1. [Authentication](#authentication) - **CRITICAL**
+
+2. [Database](#database) - **HIGH**
+
+---
+
+## 1. TODO Section
+
+**Impact: TODO**
+
+TODO - Define your sections based on Supabase product areas or patterns.
+
+*No rules defined yet. See rules/_template.md for creating new rules.*
+
+## 1. Authentication
+
+**Impact: CRITICAL**
+
+Authentication patterns, session management, and user identity.
+
+*No rules defined yet. See rules/_template.md for creating new rules.*
+
+## 2. Database
+
+**Impact: HIGH**
+
+Database queries, schema design, and data access patterns.
+
+*No rules defined yet. See rules/_template.md for creating new rules.*
+
+## References
+
+- https://supabase.com/docs

skills/using-supabase/README.md

@@ -0,0 +1,106 @@
+# Using Supabase - Contributor Guide
+
+This repository contains Supabase development patterns and best practices optimized for AI agents and LLMs.
+
+## Quick Start
+
+```bash
+# From repository root
+npm install
+
+# Validate existing rules
+npm run validate
+
+# Build AGENTS.md
+npm run build
+```
+
+## Creating a New Rule
+
+1. **Choose a section prefix** based on the category (see `rules/_sections.md`)
+
+2. **Copy the template**:
+   ```bash
+   cp rules/_template.md rules/{prefix}-your-rule-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`
+
+## Repository Structure
+
+```
+skills/using-supabase/
+├── SKILL.md           # Agent-facing skill manifest
+├── AGENTS.md          # [GENERATED] Compiled rules document
+├── README.md          # This file
+├── metadata.json      # Version and metadata
+├── PRODUCT_TEMPLATE.md # Template for product teams
+├── references/        # Reference documentation
+└── rules/
+    ├── _template.md      # Rule template
+    ├── _sections.md      # Section definitions
+    ├── _contributing.md  # Writing guidelines
+    └── *.md              # Individual rules
+```
+
+## Rule File Structure
+
+See `rules/_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):**
+
+```typescript
+// Comment explaining what's wrong
+[Bad code example]
+```
+````
+
+**Correct (description):**
+
+```typescript
+// Comment explaining why this is better
+[Good code example]
+```
+
+```
+## Writing Guidelines
+
+See `rules/_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
+4. **Self-contained examples** - Complete, runnable code
+5. **Semantic naming** - Use meaningful names
+
+## Impact Levels
+
+| Level | Improvement | Examples |
+|-------|-------------|----------|
+| CRITICAL | 10-100x or prevents failure | Security vulnerabilities, data loss |
+| HIGH | 5-20x | Architecture decisions, core functionality |
+| MEDIUM-HIGH | 2-5x | Design patterns, common anti-patterns |
+| MEDIUM | 1.5-3x | Optimization, best practices |
+| LOW-MEDIUM | 1.2-2x | Configuration, tooling |
+| LOW | Incremental | Advanced techniques, edge cases |
+```

skills/using-supabase/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: using-supabase
+description: Comprehensive Supabase development guide. Use this skill when building applications with Supabase services, integrating Supabase APIs, or following Supabase best practices.
+license: MIT
+metadata:
+  author: supabase
+  version: "1.0.0"
+---
+
+# Using Supabase
+
+Comprehensive development guide for building applications with Supabase, maintained by Supabase. Contains rules and patterns for using Supabase services effectively, prioritized by impact.
+
+## When to Apply
+
+Reference these guidelines when:
+- Building applications with Supabase
+- Integrating Supabase services into existing projects
+- Following Supabase best practices
+- Troubleshooting Supabase-related issues
+- Configuring Supabase for production deployments
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | TODO | TODO | `todo-` |
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/todo-example.md
+rules/_sections.md
+```
+
+Each rule file contains:
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+- Supabase-specific notes
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`

skills/using-supabase/rules/_contributing.md

@@ -0,0 +1,123 @@
+# Writing Guidelines for Supabase Rules
+
+This document provides guidelines for creating effective Supabase best practice rules that work well with AI agents and LLMs.
+
+## Key Principles
+
+### 1. Concrete Transformation Patterns
+
+Show exact code rewrites. Avoid philosophical advice.
+
+**Good:** "Use `supabase.auth.getUser()` instead of `supabase.auth.getSession()` for server-side auth"
+**Bad:** "Handle authentication properly"
+
+### 2. Error-First Structure
+
+Always show the problematic pattern first, then the solution. This trains agents to recognize anti-patterns.
+
+```markdown
+**Incorrect (client-side only):** [bad example]
+
+**Correct (server-side validation):** [good example]
+```
+
+### 3. Quantified Impact
+
+Include specific metrics when possible. Helps agents prioritize fixes.
+
+**Good:** "Prevents unauthorized access", "Reduces latency by 50%", "Eliminates race conditions"
+**Bad:** "Better", "More secure", "Faster"
+
+### 4. Self-Contained Examples
+
+Examples should be complete and runnable. Include imports and setup when needed.
+
+```typescript
+import { createClient } from "@supabase/supabase-js";
+
+const supabase = createClient(url, key);
+
+// Now show the pattern
+const { data, error } = await supabase.from("users").select("*");
+```
+
+### 5. Semantic Naming
+
+Use meaningful variable and table names. Names carry intent for LLMs.
+
+**Good:** `users`, `posts`, `session`, `authUser`
+**Bad:** `table1`, `data1`, `result`, `x`
+
+---
+
+## Code Example Standards
+
+### TypeScript/JavaScript Formatting
+
+```typescript
+// Use clear formatting and meaningful names
+const { data: users, error } = await supabase
+  .from("users")
+  .select("id, email, created_at")
+  .eq("is_active", true);
+```
+
+### Comments
+
+- Explain _why_, not _what_
+- Highlight security implications
+- Point out common pitfalls
+
+### Language Tags
+
+- `typescript` - TypeScript/JavaScript code
+- `sql` - SQL queries
+- `bash` - CLI commands
+
+---
+
+## Impact Level Guidelines
+
+| Level | Improvement | Use When |
+|-------|-------------|----------|
+| **CRITICAL** | 10-100x or prevents failure | Security vulnerabilities, data exposure, breaking changes |
+| **HIGH** | 5-20x | Architecture decisions, core functionality |
+| **MEDIUM-HIGH** | 2-5x | Common anti-patterns, reliability issues |
+| **MEDIUM** | 1.5-3x | Optimization, best practices |
+| **LOW-MEDIUM** | 1.2-2x | Configuration, tooling |
+| **LOW** | Incremental | Advanced patterns, edge cases |
+
+---
+
+## Reference Standards
+
+**Primary Sources:**
+
+- Official Supabase documentation
+- Supabase GitHub examples
+- Supabase blog posts
+
+**Format:**
+
+```markdown
+Reference: [Supabase Auth Docs](https://supabase.com/docs/guides/auth)
+```
+
+---
+
+## Review Checklist
+
+Before submitting a rule:
+
+- [ ] Title is clear and action-oriented
+- [ ] Impact level matches the severity
+- [ ] impactDescription includes quantification
+- [ ] Explanation is concise (1-2 sentences)
+- [ ] Has at least 1 **Incorrect** code example
+- [ ] Has at least 1 **Correct** code example
+- [ ] Code uses semantic naming
+- [ ] Comments explain _why_, not _what_
+- [ ] Trade-offs mentioned if applicable
+- [ ] Reference links included
+- [ ] `npm run validate` passes
+- [ ] `npm run build` generates correct output

skills/using-supabase/rules/_sections.md

@@ -0,0 +1,23 @@
+# Section Definitions
+
+This file defines the rule categories for using Supabase. Rules are automatically assigned to sections based on their filename prefix.
+
+---
+
+## 1. TODO Section (todo)
+**Impact:** TODO
+**Description:** TODO - Define your sections based on Supabase product areas or patterns.
+
+<!--
+Example section format:
+
+## 1. Authentication (auth)
+**Impact:** CRITICAL
+**Description:** Authentication patterns, session management, and user identity.
+
+## 2. Database (db)
+**Impact:** HIGH
+**Description:** Database queries, schema design, and data access patterns.
+
+Add sections as needed for each product area or cross-cutting concern.
+-->

skills/using-supabase/rules/_template.md

@@ -0,0 +1,28 @@
+---
+title: Clear, Action-Oriented Title (e.g., "Use Server-Side Auth for Protected Routes")
+impact: MEDIUM
+impactDescription: Brief quantified benefit
+tags: relevant, keywords
+---
+
+## [Rule Title]
+
+[1-2 sentence explanation of the problem and why it matters. Focus on impact.]
+
+**Incorrect (describe the problem):**
+
+```typescript
+// Comment explaining what makes this problematic
+// Bad code example
+```
+
+**Correct (describe the solution):**
+
+```typescript
+// Comment explaining why this is better
+// Good code example
+```
+
+[Optional: Additional context, edge cases, or trade-offs]
+
+Reference: [Supabase Docs](https://supabase.com/docs)