MCP gives an agent access to tools, but a skill provides product-specific instructions that the model may otherwise miss.
2
Supabase put security rules that agents must not skip directly in skill.md instead of hiding them in reference files.
3
Evals across Claude and GPT models found that MCP combined with the Supabase skill outperformed MCP alone and the baseline condition.
Summary
Pedro Rodrigues explains how Supabase built an agent skill for a product with database, authentication, storage, and security features. The motivation was practical: an agent given MCP created a Postgres view over a table protected by row-level security, but failed to set security_invoker = true. The resulting view could expose data that the table would normally protect. Adding the skill gave the agent the missing product guidance. Rodrigues describes three design rules. Skills should point to current documentation rather than copy it. Instructions that must not be missed, especially security checks, belong in skill.md because agents often skip reference files. Product teams should also describe preferred workflows, such as changing schemas directly in development, running an advisor, then creating a migration. Supabase tested six scenarios across four agents from Claude and Codex in three conditions. MCP plus the skill produced the highest completeness scores on every tested model.
Agents need current product guidance for unfamiliar or changed tasks
Rodrigues says agents can handle mundane work, but they need guidance when a task concerns something they have not seen or a product has changed since training. At Supabase, agents missed row-level security instructions and relied on stale training data. They also tended to avoid finding fresh information. The team wanted to guide agents toward workflows that worked well with Supabase. This frames the skill as a way to supply product-specific operating instructions, rather than as a replacement for the agent's general reasoning ability.
A skill packages progressive instructions and optional resources
A skill is a folder containing instructions, scripts, and resources that an agent discovers progressively. Its front matter includes a name and description, which help the agent decide when to load it. The main instructions live in skill.md. Optional scripts can perform actions, while reference files hold material that does not need to enter the context immediately. Rodrigues presents this structure as a way to control what the agent loads and when it loads it.
The RLS view test exposed the difference between tools and guidance
Supabase gave the same agent a collaboration-app task: create a SQL view over a table that already had row-level security. With MCP alone, the agent failed to include security_invoker = true. In Postgres, Rodrigues explains, the view can then bypass the table's row-level security and expose data that should remain protected. The agent with the Supabase skill applied the flag correctly. The MCP connection supplied access to the integration, while the skill supplied the security detail the agent did not know.
Skills should link to living documentation instead of copying it
Rodrigues advises skill authors not to duplicate their product documentation. The skill should tell the agent where the current source of truth is and how to find it. He says agents need persistent guidance to search the web or documentation instead of defaulting to training data. Supabase also experimented with exposing documentation through SSH, allowing agents to browse it as a remote filesystem using familiar Linux tools. He presents this as an experiment intended to make current information easier for agents to find.
Instructions that cannot be missed belong in skill.md
Rodrigues's second rule is that anything an agent can skip will be skipped. Fetching online information costs effort, and agents often prefer their training data. The same problem appears with reference files. Even after loading a skill, an agent may not open its references, and it is unlikely to load several files when the task needs information from each. Supabase first put its security checklist in a reference file and saw agents miss it. The team moved it into skill.md because the rule had to be present from the start.
Product skills should prescribe workflows that have worked
Rodrigues tells product teams to be opinionated about how agents should use their products. For Supabase schema work, the recommended workflow is to make direct DDL changes on a development or staging database. Once the schema is acceptable, the agent should run Supabase's advisor for security or performance issues, fix those issues, and only then create a migration file. This avoids making a new migration after every exploratory schema change. Supabase considers this workflow specific enough to belong in its skill.
Evals showed that MCP and skills solve different parts of the problem
Supabase evaluated six scenarios from ongoing projects across four agents from Claude and Codex, using a completeness score and three conditions: no MCP or skill, MCP alone, and MCP plus the skill. The tested agents included Claude Code with Opus 4.6 and Sonnet 4.6, plus Codex with GPT 5.4 and GPT 5.4 mini. The combined condition outperformed the others on every model tested. Rodrigues concludes that the tools were already available through MCP, while the skill supplied the instructions for using them correctly.
Skills should start small and distribution is still unsettled
Rodrigues recommends pointing to a single source of truth, giving clear product opinions, and starting with a minimal skill before expanding it through new versions. He also says skill distribution remains unresolved. Supabase currently packages skills inside repositories, using plugin directories such as .claude or .cursor when appropriate. Vercel's skills package and plugins that bundle MCP servers are other approaches, though some are model-specific. There is not yet one general registry or package manager for skills.
