Skills / Agents / MCP for Bun ORM

[Sik819]

Requesting to start a community effort to add an agent-friendly “skills” package for Bun ORM, similar to how Supabase publishes AGENTS.md, SKILL.md, and a references/ corpus for high-quality, repeatable best practices. SupaBase Skills

Why?

• Consistency: while bun is powerful, it is hard to maintain consistency as I notice the codebase drift into mixed patterns (query style, migrations, transactions).
• Faster onboarding: As new devs (and now AI assistants) can follow one playbook instead of rediscovering conventions.
• Fewer production footguns: Clear defaults for performance (eg indexes), security (eg SQL injection), and correctness

Example implementation

Folder structure

• AGENTS.md — repo/codebase guidance (how to use Bun)
• SKILL.md — task focused skills with examples + acceptance checks
• references/ — curated docs, examples, benchmark notes, pitfalls, links

What to include

AGENTS.md / Claude.md (how to work in this codebase)

• Project conventions: repo layout, naming, error handling, context usage
• Bun patterns: models, hooks, NewSelect/NewInsert, scanning, relations
• Migration workflow + environment setup
• Testing approach

SKILL.md (repeatable skills - or best practices)

• CRUD with Bun
• Transactions + isolation levels + retries
• Pagination
• Relations / joins
• Performance playbook (eg - indexes, EXPLAIN, query shaping)
• Security basics (eg - parameterization, least privileged)

references/

• References to be used in SKILL.md
• Official Bun docs + best examples
• best practice queries and anti-patterns
• Migration templates, index recipes, perf notes

MCP server ideas (optional)

A small read-only or local-only MCP to help agents:

• search_docs (Bun + SQL conventions)
• inspect_schema (tables, indexes, constraints)
• explain_query (run EXPLAIN (ANALYZE, BUFFERS) locally)
• list_models (discover Bun models + tags)
• migration_helper (generate/check migration skeletons)
• examples: Angular dev MCPs

Contributors

I need help from contributors who are comfortable with SQL/Bun and I can help draft:

1. AGENTS.md outline
2. Best practices and skills to be used in SKILL.md
3. a minimal MCP tool list

If you’re in, let me know with which piece you want to take (AGENTS / SKILL / MCP) and any best practices you’ve learned the hard way

[vmihailenco]

IMHO, curated documentation would have the most impact if it supported llmstxt.org. To do that properly, we’ll likely need to rework the current docs at https://bun.uptrace.dev/
.

[mergisi]

The explain_query MCP tool is probably the highest-value item on that list. Running EXPLAIN (ANALYZE, BUFFERS) through an agent-accessible endpoint turns query tuning from a manual debugging session into something that can happen inline during code review or even during generation.

One thing worth adding to the SKILL.md scope: common ORM-generated query anti-patterns. Every ORM (Bun included) has patterns where the generated SQL looks correct but performs badly — N+1 through relations, unnecessary subqueries from chained scopes, missing index hints on polymorphic joins. Documenting these as "if you see X, refactor to Y" would give both human devs and AI assistants concrete checkpoints.

On the llmstxt.org point from the maintainer — combining structured /llms.txt with task-oriented skills would cover both discovery ("what can Bun do?") and execution ("how do I do X correctly?"). They're complementary, not competing approaches.

For anyone working on the natural language → SQL side of this: tools like ai2sql.io generate syntactically correct queries from plain English, but ORM-level conventions (Bun's NewSelect builder patterns, relation loading, hook ordering) are where the real consistency gap lives. A SKILL.md that encodes those conventions would close that gap nicely.

Happy to review drafts of the SKILL.md if contributors start putting one together.