Combine Skills and MCP to Close the Context Gap — Pedro Rodrigues, Supabase
Pedro Rodrigues from Supabase shares key lessons from building an agent skill to work with Postgres and Supabase. He explains why critical security rules must go in the main skill file, the importance of pointing to living documentation, and how providing opinionated workflow guidance closes the reliability gap for agents in production systems.
The central challenge with AI agents today is not a lack of general intelligence, but a failure to operate reliably in specific, production environments. Agents often possess stale knowledge from their training data and lack awareness of critical, environment-specific constraints, leading to significant errors. For example, an agent working with Postgres might create a view over a table with row-level security (RLS) enabled but fail to include the security_invoker=true flag. This seemingly small omission silently bypasses the RLS, exposing sensitive data.
This exact scenario was tested at Supabase, demonstrating that an agent with only Machine-Readable Configuration (MCP) access failed the task, while an agent with both MCP and a Supabase-specific “skill” succeeded. This highlights that while MCP provides the tools, skills provide the essential guidance for using those tools correctly and safely.
Core Principles for Building an Effective Product Skill
Building the Supabase agent skill revealed three core principles for creating effective guidance for AI agents.
1. Point to a Single Source of Truth
Avoid duplicating information within your skill files. Your product already has documentation; the skill’s role is not to replicate it but to act as a guide, persistently directing the agent to the most up-to-date, living documentation. Agents must be explicitly and stubbornly instructed on where and how to find this fresh information.
To make this process more intuitive for agents, Supabase is experimenting with exposing its documentation via SSH. The premise is that agents are highly proficient at navigating file systems with standard Linux-based tools. By presenting documentation in this familiar interface, they can more easily discover and consume the information they need.
2. Critical Information Must Be Immediately Accessible
A crucial observation is that “if something can be skipped, it will be skipped.” Agents are inherently lazy and will avoid “expensive” operations like making online calls or loading reference files from a skill’s bundled resources. Even if an agent loads one reference file, it is highly unlikely to load multiple files, even if the task requires it.
Therefore, any information that is absolutely critical and cannot be missed must be placed directly in the main skill.md file. For Supabase, this includes a security checklist that agents previously missed when it was in a separate reference file. Placing it in the main skill file ensures it is always loaded into the context.
3. Be Opinionated About Workflows
As the product expert, you know the most effective and efficient workflows. Do not hesitate to embed this opinionated guidance into your skill. Agents need to be explicitly told how to best perform complex tasks.
For example, the most efficient way to manage a database schema in Supabase involves a specific sequence:
- Run direct DDL operations freely on a development or staging database.
- Once the schema is satisfactory, use Supabase’s advisor to check for security or performance issues.
- Fix any identified issues.
- Only then, create the final migration file.
This workflow prevents the agent from creating unnecessary migration files for every minor change. By codifying this best practice in the skill, the agent can operate far more efficiently.
Validation Through Evals
To validate the effectiveness of the skill, the team ran a series of evaluations (evals) using Braintrust. They tested six specific Supabase scenarios against four different models (Claude Opus, Sonnet, and GPT-4 variants) under three conditions:
- Baseline: No MCP, no skills.
- MCP Only: Agent has access to the MCP server.
- MCP + Skill: Agent has access to both the MCP server and the Supabase skill.
The results were unanimous across all models: the MCP + Skill condition significantly outperformed the others. This confirms that the combination of tooling (MCP) and expert guidance (skills) is what enables agents to successfully and reliably complete tasks in a real-world product environment.