AI Agents Know About Supabase. They Don't Always Use It Right.
Supabase has introduced Agent Skills, an open-source set of instructions designed to guide AI coding agents in building on Supabase correctly. This initiative addresses common pitfalls such as incorrect use of RLS policies, outdated training data, and improper CLI command usage.
Introduction to Supabase Agent Skills
Supabase has released an open-source initiative called Agent Skills, aimed at improving the accuracy and security of AI coding agents when working with Supabase. This toolset provides agents with structured guidance on how to interact with Supabase's ecosystem, ensuring that they follow best practices and avoid common mistakes.
Why Agent Skills Matter
While AI agents have access to a wealth of knowledge, including Supabase's codebase and documentation, they often fail to apply this knowledge correctly. Common issues include skipping Row Level Security (RLS) policies, using outdated CLI commands, and relying on training data that may not reflect the latest changes in Supabase's tools and APIs.
Key Areas Covered by Agent Skills
Agent Skills focuses on four critical areas: documentation access, security, tooling workflow, and schema management. These areas are essential for ensuring that AI agents produce secure, up-to-date, and functional code when working with Supabase.
Documentation Access
One of the core principles of Agent Skills is to ensure that agents always verify information against the latest Supabase documentation. This is crucial because Supabase evolves rapidly, and relying solely on training data can lead to outdated or incorrect implementations. The skill instructs agents to use three methods to access documentation: the MCP search_docs tool, fetching markdown files directly from Supabase's URLs, and using native web search tools when necessary.
Security and RLS
Supabase has specific security requirements that AI agents may overlook. Agent Skills includes an inline checklist of security best practices that agents must follow. These include using app_metadata instead of user_metadata for authorization, ensuring that views are created with security_invoker = true to respect RLS policies, and properly configuring permissions for storage operations. These guidelines are embedded directly into the skill to ensure that agents cannot skip them.
Tooling Workflow
Agent Skills provides guidance on how to interact with Supabase through both the Supabase MCP server and the Supabase CLI. For CLI-based workflows, agents are instructed to use the --help flag to discover available commands and their parameters. For MCP-based workflows, the skill includes a troubleshooting guide to help agents diagnose and resolve connection issues with the MCP server.
Schema Management
As AI agents become more autonomous, managing database schema changes becomes increasingly important. Agent Skills encourages agents to modify schemas directly using the execute_sql MCP tool or the supabase db query CLI command, rather than relying on migration-based workflows. This approach allows for faster iteration during development. Once the schema stabilizes, agents are advised to run Supabase database advisors to identify potential security or performance issues before formalizing changes with a migration.
Implementation and Testing
Supabase tested Agent Skills using a framework similar to OpenAI's approach for evaluating agent skills. This involved defining success criteria, manually testing the skill, and then moving to automated evaluations. The testing process focused on three key metrics: skill loading, task completeness, and the accuracy of generated code and tool calls.
Conclusion
Supabase Agent Skills represents a significant step forward in ensuring that AI agents can work effectively and securely with Supabase. By embedding critical guidance directly into the skill and focusing on documentation access, security, tooling, and schema management, this initiative helps agents avoid common pitfalls and produce more reliable code. As AI agents continue to evolve, tools like Agent Skills will play a crucial role in bridging the gap between knowledge and correct implementation.
Source: Supabase. Analysis based on publicly available information; no hands-on testing is claimed.
