supabase-postgres-best-practices/IMPLEMENTATION_GUIDE.md

Supabase Skills Package - Implementation Guide

Status: Phase 1 Complete ✅

This guide breaks down the Supabase skills package implementation into manageable, iterative tasks.

---

✅ Completed So Far

1. Planning Phase (Complete)

• Explored postgres-best-practices structure, supabase-js codebase, and skill-creator guidelines
• Designed unified build system supporting multiple skill types
• Created comprehensive plan at .claude/plans/immutable-scribbling-galaxy.md

2. Build System Refactor (Complete ✅)

• ✅ Created feature branch feature/supabase-skill
• ✅ Renamed packages/postgres-best-practices-build → packages/skills-build
• ✅ Created subdirectories src/postgres/ and src/supabase/
• ✅ Moved postgres files to src/postgres/
• ✅ Updated BUILD_DIR path in postgres/config.ts
• ✅ Updated type imports in postgres module files
• ✅ Extended shared types (SkillConfig, SkillType, Resource)
• ✅ Created skills-config.ts registry
• ✅ Created CLI interface (cli.ts)
• ✅ Updated package.json scripts to use CLI
• ✅ Verified postgres build works with new system
• ✅ Committed all changes (commit: 345b560)

---

✅ Completed Tasks (Phase 1)

All tasks 1-6 have been completed successfully! The unified build system foundation is now in place.

Task 1: Complete Postgres Module Updates ✅

• Tested postgres build after refactoring
• Added temporary build:postgres script
• Verified AGENTS.md generation works correctly

Task 2: Extend Shared Types ✅

• Added SkillConfig, SkillType interfaces
• Added Resource, ReferenceParseResult for reference-based skills

Task 3: Create Skills Configuration ✅

• Created src/skills-config.ts registry
• Defined postgres-best-practices and supabase configs

Task 4: Create Basic CLI Interface ✅

• Created src/cli.ts with validate/build commands
• Added support for --skill flag to target specific skills

Task 5: Update package.json ✅

• Renamed package to "skills-build"
• Updated all scripts to use new CLI
• Added skill-specific scripts (build:postgres, build:supabase, etc.)

Task 6: Commit Build System Refactor ✅

• Committed all changes (commit: 345b560)
• Verified postgres build still works

---

🚧 Next Steps (Phase 2: Supabase Module)

You're now ready to create the supabase module! The next phase focuses on building the reference-based skill system.

📦 Tasks 7-12: Create Supabase Module

After completing tasks 1-6, you'll be ready to create the supabase module. Here's a preview:

Task 7: Create Supabase Config

File: packages/skills-build/src/supabase/config.ts

• Similar to postgres/config.ts
• Define paths for supabase skill

Task 8: Create Supabase Parser

File: packages/skills-build/src/supabase/parser.ts

• Parse markdown reference files
• Extract headings, code blocks, "Incorrect"/"Correct" patterns

Task 9: Create Supabase Validator

File: packages/skills-build/src/supabase/validate.ts

• Validate reference file structure
• Check for required sections

Task 10: Create Supabase Builder

File: packages/skills-build/src/supabase/build.ts

• Read all reference files from references/
• Generate AGENTS.md

Task 11: Update CLI for Supabase

File: packages/skills-build/src/cli.ts

• Import supabase module
• Add supabase to build/validate logic

Task 12: Test Unified Build System

npm run build  # Should build both skills
npm run validate  # Should validate both skills

---

📝 Task 13-20: Create Supabase Content (Final Phase)

After the build system is complete, create the actual supabase skill content:

1. Create skills/supabase/ directory structure
2. Write SKILL.md, metadata.json, README.md
3. Create references/supabase-js.md (hub file)
4. Create 7 sub-resource files in references/supabase-js/:
   • client-lifecycle.md
   • error-handling.md
   • auth-patterns.md
   • database-queries.md
   • realtime-subscriptions.md
   • storage-operations.md
   • common-mistakes.md
5. Test skill loading and progressive disclosure

---

🎯 Quick Reference Commands

# Navigate to build package
cd packages/skills-build

# Install dependencies
npm install

# Build postgres only
npm run build:postgres

# Build all skills
npm run build

# Validate postgres only
npm run validate:postgres

# Validate all skills
npm run validate

# Check status
git status

# Commit progress
git add .
git commit -m "your commit message"

---

📋 Success Criteria for Phase 1

• ✅ Postgres build still works after refactoring
• ✅ Unified build system can build postgres
• ✅ CLI interface works for postgres
• ✅ No regressions in postgres AGENTS.md generation
• ✅ Code is committed to feature branch

---

📚 Resources

• Full Plan: .claude/plans/immutable-scribbling-galaxy.md
• Postgres Build System: packages/skills-build/src/postgres/
• Current Branch: feature/supabase-skill

---

💡 Tips

1. Test frequently: Run npm run build:postgres after each change
2. Commit often: Small commits make it easier to track progress
3. One task at a time: Complete tasks 1-6 before moving to supabase module
4. Ask for help: If stuck, refer back to the full plan or ask questions

---

Next Session Starting Point

When you're ready to continue:

1. Start with Task 7: Create Supabase Config (Phase 2)
2. Work through tasks sequentially (7 → 8 → 9 → ...)
3. Test after each task
4. Commit progress regularly

Phase 1 is complete! The unified build system is now ready for the supabase module implementation. 🚀