refactor: generic skills build system with auto-discovery

.github/workflows/ci.yml

@@ -1,4 +1,4 @@
-name: Postgres Best Practices CI
+name: Skills CI
 
 on:
   push:
@@ -23,7 +23,7 @@ jobs:
         run: npm run ci:check
 
   validate-and-build:
-    name: Validate and Build
+    name: Validate and Build Skills
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -33,22 +33,22 @@ jobs:
           node-version: '20'
 
       - name: Install dependencies
-        working-directory: packages/postgres-best-practices-build
+        working-directory: packages/skills-build
         run: npm install
 
-      - name: Validate rule files
-        working-directory: packages/postgres-best-practices-build
+      - name: Validate all skills
+        working-directory: packages/skills-build
         run: npm run validate
 
-      - name: Build AGENTS.md
-        working-directory: packages/postgres-best-practices-build
+      - name: Build all skills
+        working-directory: packages/skills-build
         run: npm run build
 
       - name: Check for uncommitted changes
         run: |
-          if [[ -n $(git status --porcelain skills/postgres-best-practices/AGENTS.md) ]]; then
-            echo "Error: AGENTS.md is not up to date"
+          if [[ -n $(git status --porcelain 'skills/*/AGENTS.md') ]]; then
+            echo "Error: AGENTS.md files are not up to date"
             echo "Run 'npm run build' and commit the changes"
-            git diff skills/postgres-best-practices/AGENTS.md
+            git diff skills/*/AGENTS.md
             exit 1
           fi

AGENTS.md

@@ -1,120 +1,71 @@
 # AGENTS.md
 
-This file provides guidance to AI coding agents (Claude Code, Cursor, Copilot,
-etc.) when working with code in this repository.
+Guidance for AI coding agents working with this repository.
 
-## Repository Overview
-
-A collection of Postgres best practices skills for AI coding agents, maintained
-by Supabase. Skills are packaged instructions that extend agent capabilities for
-database optimization.
-
-## Creating a New Rule
-
-### Directory Structure
+## Repository Structure
 
 ```
 skills/
-  postgres-best-practices/
-    SKILL.md              # Required: skill definition
+  {skill-name}/
+    metadata.json         # Required: skill metadata
     AGENTS.md             # Generated: compiled rules
-    metadata.json         # Required: version and metadata
     rules/
-      _template.md        # Template for new rules
-      _sections.md        # Section definitions
-      _contributing.md    # Writing guidelines
-      {prefix}-{name}.md  # Individual rule files
+      _sections.md        # Required: section definitions
+      {prefix}-{name}.md  # Rule files
 
 packages/
-  postgres-best-practices-build/
-    src/                  # Build system source
-    package.json          # NPM scripts
+  skills-build/           # Generic build system for all skills
 ```
 
-### Naming Conventions
+## Commands
 
-- **Rule files**: `{prefix}-{kebab-case-name}.md` (e.g.,
-  `query-missing-indexes.md`)
-- **Prefixes determine section**: `query-`, `conn-`, `schema-`, `lock-`,
-  `security-`, `data-`, `monitor-`, `advanced-`
-- **Special files**: Prefixed with `_` (e.g., `_template.md`, `_sections.md`)
+```bash
+npm run build                    # Build all skills
+npm run build -- {skill-name}    # Build specific skill
+npm run validate                 # Validate all skills
+npm run validate -- {skill-name} # Validate specific skill
+```
 
-### Rule File Format
+## Creating a New Skill
 
-````markdown
+1. Create directory: `mkdir -p skills/{name}/rules`
+2. Add `metadata.json` with version, organization, abstract
+3. Add `rules/_sections.md` defining sections
+4. Add rule files: `{prefix}-{rule-name}.md`
+5. Run `npm run build`
+
+## Rule File Format
+
+```markdown
 ---
-title: Clear, Action-Oriented Title
+title: Action-Oriented Title
 impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
-impactDescription: Quantified benefit (e.g., "10-100x faster")
-tags: relevant, keywords
+impactDescription: Quantified benefit
+tags: keywords
 ---
 
-## [Title]
+## Title
 
-[1-2 sentence explanation]
+1-2 sentence explanation.
 
-**Incorrect (description):**
+**Incorrect:**
+\`\`\`sql
+-- bad example
+\`\`\`
 
-```sql
--- Comment explaining what's wrong
-[Bad SQL example]
+**Correct:**
+\`\`\`sql
+-- good example
+\`\`\`
 ```
 
-**Correct (description):**
-
-```sql
--- Comment explaining why this is better
-[Good SQL example]
-```
-````
-
-### Best Practices for Context Efficiency
-
-Skills are loaded on-demand. To minimize context usage:
-
-- **Keep rules focused** - One optimization pattern per rule
-- **Write specific titles** - Helps the agent know exactly when to apply
-- **Use progressive disclosure** - Reference supporting files when needed
-- **Self-contained examples** - Complete, runnable SQL
-- **Quantify impact** - Include specific metrics (10x faster, 50% smaller)
-
-### Build System
-
-After creating or updating rules:
-
-```bash
-cd packages/postgres-best-practices-build
-npm install
-npm run validate  # Check rule format
-npm run build     # Generate AGENTS.md
-```
+## Impact Levels
 
-**Automatic Section Ordering**: The build system automatically reads section order
-from `_sections.md`. To reorder sections (e.g., promoting Security from MEDIUM-HIGH
-to CRITICAL priority), simply edit the section numbers in `_sections.md` and
-rebuild. The section mapping is generated dynamically, so manual updates to
-`config.ts` are no longer needed.
-
-### Impact Levels
-
-| Level       | Improvement | Examples                               |
-| ----------- | ----------- | -------------------------------------- |
-| CRITICAL    | 10-100x     | Missing indexes, connection exhaustion |
-| HIGH        | 5-20x       | Wrong index types, poor partitioning   |
-| MEDIUM-HIGH | 2-5x        | N+1 queries, RLS optimization          |
-| MEDIUM      | 1.5-3x      | Redundant indexes, stale statistics    |
-| LOW-MEDIUM  | 1.2-2x      | VACUUM tuning, config tweaks           |
-| LOW         | Incremental | Advanced patterns, edge cases          |
-
-### File Prefix to Section Mapping
-
-| Prefix      | Section                  | Priority        |
-| ----------- | ------------------------ | --------------- |
-| `query-`    | Query Performance        | 1 (CRITICAL)    |
-| `conn-`     | Connection Management    | 2 (CRITICAL)    |
-| `security-` | Security & RLS           | 3 (CRITICAL)    |
-| `schema-`   | Schema Design            | 4 (HIGH)        |
-| `lock-`     | Concurrency & Locking    | 5 (MEDIUM-HIGH) |
-| `data-`     | Data Access Patterns     | 6 (MEDIUM)      |
-| `monitor-`  | Monitoring & Diagnostics | 7 (LOW-MEDIUM)  |
-| `advanced-` | Advanced Features        | 8 (LOW)         |
+| Level       | Improvement                   | Use For                                                    |
+| ----------- | ----------------------------- | ---------------------------------------------------------- |
+| CRITICAL    | 10-100x or prevents failure   | Security vulnerabilities, data loss, breaking changes      |
+| HIGH        | 5-20x or major quality gain   | Architecture decisions, core functionality, scalability    |
+| MEDIUM-HIGH | 2-5x or significant benefit   | Design patterns, common anti-patterns, reliability         |
+| MEDIUM      | 1.5-3x or noticeable gain     | Optimization, best practices, maintainability              |
+| LOW-MEDIUM  | 1.2-2x or minor benefit       | Configuration, tooling, code organization                  |
+| LOW         | Incremental or edge cases     | Advanced techniques, rare scenarios, polish                |

CONTRIBUTING.md

@@ -2,10 +2,9 @@
 
 Thank you for contributing to Supabase Agent Skills! Here's how to get started:
 
-[1. Getting Started](#getting-started) [2. Issues](#issues)
-[3. Pull Requests](#pull-requests)
-[4. Contributing New Rules](#contributing-new-rules)
-[5. Extending Existing Skills](#extending-existing-skills)
+[1. Getting Started](#getting-started) | [2. Issues](#issues) |
+[3. Pull Requests](#pull-requests) | [4. Contributing New Rules](#contributing-new-rules) |
+[5. Creating a New Skill](#creating-a-new-skill)
 
 ## Getting Started
 
@@ -49,6 +48,68 @@ npm run build     # Generate AGENTS.md from rules
 
 Both commands must complete successfully.
 
+## Contributing New Rules
+
+To add a rule to an existing skill:
+
+1. Navigate to `skills/{skill-name}/rules/`
+2. Copy `_template.md` to `{prefix}-{your-rule-name}.md`
+3. Fill in the frontmatter (title, impact, tags)
+4. Write explanation and examples (Incorrect/Correct)
+5. Run validation and build:
+
+```bash
+npm run validate
+npm run build
+```
+
+## Creating a New Skill
+
+To create an entirely new skill:
+
+### 1. Create the directory structure
+
+```bash
+mkdir -p skills/my-skill/rules
+```
+
+### 2. Create metadata.json
+
+```json
+{
+  "version": "1.0.0",
+  "organization": "Your Org",
+  "date": "January 2026",
+  "abstract": "Brief description of this skill."
+}
+```
+
+### 3. Create rules/_sections.md
+
+```markdown
+## 1. First Category (first)
+**Impact:** HIGH
+**Description:** What this category covers.
+
+## 2. Second Category (second)
+**Impact:** MEDIUM
+**Description:** What this category covers.
+```
+
+### 4. Create rule files
+
+Name files as `{prefix}-{rule-name}.md` where prefix matches a section.
+
+Example: `first-example-rule.md` for section "First Category"
+
+### 5. Build
+
+```bash
+npm run build
+```
+
+The build system auto-discovers skills. No configuration needed.
+
 ## Questions or Feedback?
 
 - Open an Issue for bugs or suggestions

package.json

@@ -5,8 +5,8 @@
 	"license": "MIT",
 	"description": "Official Supabase agent skills",
 	"scripts": {
-		"build": "npm --prefix packages/postgres-best-practices-build run build",
-		"validate": "npm --prefix packages/postgres-best-practices-build run validate",
+		"build": "npm --prefix packages/skills-build run build",
+		"validate": "npm --prefix packages/skills-build run validate",
 		"format": "biome format --write .",
 		"format:check": "biome format .",
 		"lint": "biome lint --write .",