mirror of
https://github.com/supabase/agent-skills.git
synced 2026-01-26 19:09:51 +08:00
refactor: generic skills build system with auto-discovery (#8)
* refactor: generic skills build system with auto-discovery - Rename postgres-best-practices-build → skills-build - Add auto-discovery: scans skills/ for subdirectories with metadata.json - Build/validate all skills or specific skill with -- argument - Update root AGENTS.md and CONTRIBUTING.md with new structure - No configuration needed to add new skills Usage: npm run build # Build all skills npm run build -- skill-name # Build specific skill npm run validate # Validate all skills Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * fix ci * more generic impact levels --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Pedro Rodrigues
151
AGENTS.md
151
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
|
||||
|
||||
- **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`)
|
||||
|
||||
### Rule File Format
|
||||
|
||||
````markdown
|
||||
---
|
||||
title: Clear, Action-Oriented Title
|
||||
impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
|
||||
impactDescription: Quantified benefit (e.g., "10-100x faster")
|
||||
tags: relevant, keywords
|
||||
---
|
||||
|
||||
## [Title]
|
||||
|
||||
[1-2 sentence explanation]
|
||||
|
||||
**Incorrect (description):**
|
||||
|
||||
```sql
|
||||
-- Comment explaining what's wrong
|
||||
[Bad SQL 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:
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
cd packages/postgres-best-practices-build
|
||||
npm install
|
||||
npm run validate # Check rule format
|
||||
npm run build # Generate AGENTS.md
|
||||
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
|
||||
```
|
||||
|
||||
**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.
|
||||
## Creating a New Skill
|
||||
|
||||
### Impact Levels
|
||||
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`
|
||||
|
||||
| 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 |
|
||||
## Rule File Format
|
||||
|
||||
### File Prefix to Section Mapping
|
||||
```markdown
|
||||
---
|
||||
title: Action-Oriented Title
|
||||
impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
|
||||
impactDescription: Quantified benefit
|
||||
tags: keywords
|
||||
---
|
||||
|
||||
| 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) |
|
||||
## Title
|
||||
|
||||
1-2 sentence explanation.
|
||||
|
||||
**Incorrect:**
|
||||
\`\`\`sql
|
||||
-- bad example
|
||||
\`\`\`
|
||||
|
||||
**Correct:**
|
||||
\`\`\`sql
|
||||
-- good example
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
## Impact Levels
|
||||
|
||||
| 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 |
|
||||
|
||||
Reference in New Issue
Block a user