diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md
new file mode 100644
index 0000000..0096431
--- /dev/null
+++ b/GETTING_STARTED.md
@@ -0,0 +1,69 @@
+# Getting Started
+
+Contributor guide for adding content to the Supabase Agent Skills.
+
+## Quick Start
+
+1. Create a reference file in `skills/supabase/references/`
+2. Use `skills/supabase/references/_template.md` as your starting point
+3. Update `skills/supabase/SKILL.md` to reference your new file
+4. Run `npm run build && npm run check`
+
+## Creating Reference Files
+
+```bash
+# Main topic
+skills/supabase/references/{feature}.md
+
+# Sub-topics (optional)
+skills/supabase/references/{feature}/{subtopic}.md
+```
+
+**Examples:**
+
+- `references/auth.md` - Authentication overview
+- `references/auth/nextjs.md` - Auth setup for Next.js
+- `references/storage.md` - Storage overview
+
+## Writing Guidelines
+
+Follow the [Agent Skills Open Standard](https://agentskills.io/) best practices:
+
+1. **Concise is key** - Only include what Claude doesn't already know
+2. **Show, don't tell** - Prefer code examples over explanations
+3. **Progressive disclosure** - Keep SKILL.md lean, put details in reference files
+4. **Concrete examples** - Include runnable code with real values
+5. **Common mistakes first** - Help agents avoid pitfalls
+
+**Good example** (~50 tokens):
+
+```typescript
+// Get user session
+const { data: { session } } = await supabase.auth.getSession();
+```
+
+**Avoid** (~150 tokens):
+
+```markdown
+Sessions are a way to track authenticated users. When a user logs in,
+a session is created. You can get the current session using the
+getSession method which returns a promise...
+```
+
+## Update SKILL.md
+
+Add your reference to the resources table:
+
+```markdown
+| Area         | Resource                | When to Use                    |
+| ------------ | ----------------------- | ------------------------------ |
+| Your Feature | `references/feature.md` | Brief description of use cases |
+```
+
+## Validate
+
+```bash
+npm run validate -- supabase   # Check files
+npm run build -- supabase      # Generate AGENTS.md
+npm run check                  # Format and lint
+```
diff --git a/skills/supabase/GETTING_STARTED.md b/skills/supabase/GETTING_STARTED.md
deleted file mode 100644
index e40ba18..0000000
--- a/skills/supabase/GETTING_STARTED.md
+++ /dev/null
@@ -1,70 +0,0 @@
-# Getting Started
-
-Welcome! This guide walks you through adding your product's content to the Supabase Agent Skills.
-
-## Quick Start
-
-After creating your branch, follow these steps:
-
-### 1. Create Your Reference File
-
-Create a new markdown file in `references/`:
-
-```bash
-# Main topic file
-references/{product-name}.md
-
-# Sub-topics (optional)
-references/{product-name}/{subtopic}.md
-```
-
-**Examples:**
-
-- `references/auth.md` - Main auth documentation
-- `references/auth/nextjs-setup.md` - Auth setup for Next.js
-- `references/storage.md` - Storage overview
-- `references/storage/upload-files.md` - File upload guide
-
-### 2. Write Your Content
-
-Use `references/_template.md` as your starting point. Include:
-
-1. **Title** - Clear heading describing the topic
-2. **Overview** - Brief explanation of what this covers
-3. **Code examples** - Show how to use the feature
-4. **Common patterns** - Real-world usage scenarios
-5. **Documentation links** - Link to official docs
-
-### 3. Update SKILL.md
-
-Add your reference to the resources table in `SKILL.md`:
-
-```markdown
-| Area           | Resource                  | When to Use              |
-| -------------- | ------------------------- | ------------------------ |
-| Your Feature   | `references/feature.md`   | Description of when      |
-```
-
-### 4. Validate and Build
-
-```bash
-npm run validate -- supabase   # Check your files
-npm run build -- supabase      # Generate AGENTS.md
-npm run check                  # Format code
-```
-
-## Writing Guidelines
-
-- **Be practical** - Show real code, not abstract concepts
-- **Be complete** - Include imports and full setup when helpful
-- **Use semantic names** - `userProfile`, `bucketName`, not `data`, `x`
-- **Link to docs** - Reference official documentation
-- **Show patterns** - Demonstrate common use cases
-
-## Existing References
-
-Check the `references/` directory for examples of existing content.
-
-## Questions?
-
-Open an issue or reach out to the AI team.
diff --git a/skills/supabase/README.md b/skills/supabase/README.md
deleted file mode 100644
index d2b0e41..0000000
--- a/skills/supabase/README.md
+++ /dev/null
@@ -1,82 +0,0 @@
-# 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/_template.md b/skills/supabase/references/_template.md
index 95c1ecb..e10af58 100644
--- a/skills/supabase/references/_template.md
+++ b/skills/supabase/references/_template.md
@@ -1,53 +1,46 @@
 ---
-title: Clear, Action-Oriented Title (e.g., "Authentication with Next.js")
-tags: auth, nextjs, setup
+title: Action-Oriented Title
+tags: relevant, keywords
 ---
 
-# [Feature/Topic Name]
+# Feature Name
 
-Brief description of what this feature does and when to use it.
+One-sentence description of what this does and when to use it.
 
-For official documentation:
-
-```bash
-curl -H "Accept: text/markdown" https://supabase.com/docs/guides/{feature}
-```
-
-## Quick Setup
+## Quick Start
 
 ```typescript
-// Installation and basic usage
+// Minimal working example with real code
+import { createClient } from "@supabase/supabase-js";
+const supabase = createClient(url, key);
+
+// Core operation
+const { data, error } = await supabase.from("table").select("*");
 ```
 
 ## Common Patterns
 
-### Pattern 1
+### Pattern Name
 
 ```typescript
-// Code example
-```
-
-### Pattern 2
-
-```typescript
-// Code example
+// Concrete example - prefer this over explanations
+const { data } = await supabase.from("users").select("id, email").eq("active", true);
 ```
 
 ## Common Mistakes
 
-1. **Mistake description**: Brief explanation and how to fix it
-2. **Another common issue**: Explanation
+**Mistake**: Brief description of what goes wrong.
 
-## Sub-Resources
+```typescript
+// Incorrect
+const data = await supabase.from("users").select(); // Missing error handling
 
-| Topic       | Resource                       |
-| ----------- | ------------------------------ |
-| Setup guide | `{feature}/setup.md`           |
-| Mistakes    | `{feature}/common-mistakes.md` |
+// Correct
+const { data, error } = await supabase.from("users").select("*");
+if (error) throw error;
+```
 
-## Documentation Resources
+## Related
 
-| Topic           | URL                                        |
-| --------------- | ------------------------------------------ |
-| Official Guide  | https://supabase.com/docs/guides/{feature} |
-| API Reference   | https://supabase.com/docs/reference        |
+- [subtopic.md](subtopic.md) - For advanced X patterns
+- [Docs](https://supabase.com/docs/guides/feature) - Official guide