skills/supabase-postgres-best-practices
1
0
Fork 0
mirror of https://github.com/supabase/agent-skills.git synced 2026-03-27 10:09:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

review skills.md and template through skill-creator skill

Browse Source
This commit is contained in:
Pedro Rodrigues
2026-01-27 16:09:05 +00:00
parent e193f97a86
commit fbfa46fbbb
4 changed files with 94 additions and 184 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
GETTING_STARTED.md Normal file
View File

@@ -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
```

70
skills/supabase/GETTING_STARTED.md
View File

@@ -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.

82
skills/supabase/README.md
View File

@@ -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

57
skills/supabase/references/_template.md
View File

@@ -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