From d359dc0e97a2907f6730bb5864162cd3fd9beb79 Mon Sep 17 00:00:00 2001
From: Pedro Rodrigues <pedro.rodrigues@supabase.io>
Date: Mon, 26 Jan 2026 21:07:34 +0000
Subject: [PATCH] add readme

---
 skills/supabase/README.md           | 82 +++++++++++++++++++++++++++++
 skills/supabase/references/.gitkeep |  0
 2 files changed, 82 insertions(+)
 create mode 100644 skills/supabase/README.md
 delete mode 100644 skills/supabase/references/.gitkeep

diff --git a/skills/supabase/README.md b/skills/supabase/README.md
new file mode 100644
index 0000000..d2b0e41
--- /dev/null
+++ b/skills/supabase/README.md
@@ -0,0 +1,82 @@
+# Supabase Skill - Contributor Guide
+
+This skill contains Supabase development 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. **Copy the template**:
+   ```bash
+   cp references/_template.md references/your-reference-name.md
+   ```
+
+2. **Fill in the content** following the template structure
+
+3. **Validate and build**:
+   ```bash
+   npm run validate
+   npm run build
+   ```
+
+4. **Review** the generated `AGENTS.md`
+
+## Skill Structure
+
+```
+skills/supabase/
+├── SKILL.md           # Agent-facing skill manifest (Agent Skills spec)
+├── AGENTS.md          # [GENERATED] Compiled references document
+├── GETTING_STARTED.md # Quick start guide
+├── README.md          # This file
+└── references/
+    ├── _template.md      # Reference template
+    ├── _sections.md      # Section definitions
+    └── *.md              # Individual references
+```
+
+## Reference File Structure
+
+See `references/_template.md` for the complete template. Key elements:
+
+```markdown
+---
+title: Clear, Action-Oriented Title
+tags: relevant, keywords
+---
+
+# [Feature/Topic Name]
+
+Brief description of what this feature does and when to use it.
+
+## Quick Setup
+
+[Installation and basic usage]
+
+## Common Patterns
+
+[Code examples for typical use cases]
+
+## Common Mistakes
+
+[Pitfalls to avoid]
+```
+
+## Writing Guidelines
+
+1. **Show concrete examples** - Include runnable code snippets
+2. **Reference official docs** - Use `curl -H "Accept: text/markdown"` for fetching docs
+3. **Common mistakes first** - Help agents avoid pitfalls
+4. **Self-contained examples** - Complete, working code
+5. **Link to resources** - Point to official documentation and related references
diff --git a/skills/supabase/references/.gitkeep b/skills/supabase/references/.gitkeep
deleted file mode 100644
index e69de29..0000000