Rodrigues Product Skill Architecture Method
Build a reusable agent skill document that closes the context gap between an AI agent's training data and your specific product, enabling agents to work correctly, safely, and efficiently with your platform.
// TL;DR
The Rodrigues Product Skill Architecture Method is a framework for building reusable skill.md documents that close the context gap between an AI agent's training data and your specific product. It ensures agents work correctly, safely, and efficiently with your platform by embedding non-negotiable rules directly in skill.md, pointing agents to live documentation instead of duplicating it, encoding opinionated workflows, and validating everything through multi-model evals. Use it whenever agents produce stale, unsafe, or workflow-incorrect outputs when interacting with your product or API.
// When should I use the Rodrigues Product Skill Architecture Method?
Use this method whenever you are building an agent skill (skill.md) for a product or platform that has security requirements, proprietary workflows, or knowledge that post-dates or differs from model training data. Trigger this when agents are producing stale, unsafe, or workflow-incorrect outputs when working with your product.
// What inputs do I need to build a product skill using the Rodrigues method?
- Product descriptionrequired
What your product does, its core features, and the primary workflows users or agents perform with it. - Known agent failure modesrequired
Specific ways agents currently get things wrong with your product — e.g. missed security steps, stale API usage, incorrect sequencing of operations. - Canonical documentation URL or sourcerequired
The single source of truth for your product's documentation that agents should be directed to for up-to-date information. - Critical non-negotiable checksrequired
Any security, compliance, or correctness requirements that an agent must never skip — these go directly into skill.md, not reference files. - Opinionated workflows
The specific ordered sequences of operations you believe are the most optimised for agents working with your product. - Existing MCP server or tool integrations
Any MCP servers or tool integrations already in place that the skill will complement.
// What are the core principles of the Rodrigues Product Skill Architecture Method?
Don't Duplicate Information
Treat the skill like documentation you already own — don't reproduce what exists elsewhere. Instead, point the agent forcefully and persistently to your single source of truth (your live documentation or docs-over-SSH interface). Be stubborn with the model: instruct it explicitly to fetch fresh information rather than defaulting to training data.
If Something Can Get Skipped, It Will Be Skipped
Agents are lazy about loading reference files — they will resist loading more than one, and rarely load two or more. Anything the agent absolutely cannot miss (security checklists, non-negotiable workflows, product-defining rules) must live directly in skill.md, not in a reference file. Reserve reference files only for supplementary detail that is genuinely optional for most tasks.
Be Opinionated
You know your product better than any model does. Don't be neutral — embed the specific workflows you have determined are most effective for agents on your platform. Define the correct sequence of operations explicitly and instruct agents to follow it, rather than leaving them to infer a workflow from general training.
Start Minimal and Iterate
Begin with the smallest viable skill.md — only the most critical, non-skippable guidance. Expand incrementally based on eval results. Don't be afraid to create new versions. The instinct to over-populate the skill upfront is a trap.
// How do you apply the Rodrigues Product Skill Architecture Method step by step?
- 1
Audit your known agent failure modes
List every way agents currently get your product wrong: security pitfalls missed, stale API patterns used, incorrect workflow ordering. This list becomes the specification for what the skill must prevent. Do not skip this — it defines the scope of the entire skill.
- 2
Identify your single source of truth
Locate the canonical, always-up-to-date documentation for your product. Determine the best interface for agents to access it (URL, SSH-exposed file system, semantic search layer). The skill will point here rather than reproducing content.
- 3
Separate must-load content from reference content
Apply the 'if it can be skipped, it will be skipped' principle. Classify every piece of guidance: if missing it would produce an incorrect or unsafe outcome, it goes into skill.md directly. Everything else is a candidate for a reference file — but assume agents will rarely load it.
- 4
Draft the skill.md with front matter, core instructions, and persistent documentation directives
The front matter (name + description) is how the agent decides when to load the skill — write it precisely. Core instructions must include: the non-negotiable security/correctness checklist, explicit instructions to fetch live documentation (be stubborn — repeat and emphasise this), and your opinionated workflows for the most common agent tasks on your product.
- 5
Encode your opinionated workflows explicitly
For each major product workflow, write the specific ordered sequence of steps the agent should follow. Do not leave sequencing implicit. Example structure: perform operation A → run advisor/linter → fix issues → only then perform operation B. Explain why this order is optimal so the agent has reasoning to anchor on, not just rules to follow blindly.
- 6
Add reference files for supplementary content only
Bundle reference files sparingly. Each reference file should be self-contained for a single sub-topic. Accept that agents will likely load at most one — design accordingly. Link to them explicitly from skill.md with clear conditions for when to load each one.
- 7
Write evals covering your known failure modes
Create a set of specific scenarios (aim for at least 6) representing realistic tasks on your product — including the cases where agents previously failed. Run these in three conditions: baseline (no MCP, no skill), MCP only, and MCP + skill. Use a graded completeness score. This tests a markdown document as if it were code — treat it with the same rigour.
- 8
Run evals across multiple models and vendors
Test across at least two model families to confirm the skill is agent-agnostic. A skill that only works for one model is fragile. If a model fails where others pass, investigate whether the skill.md language needs to be strengthened for that model's tendencies.
- 9
Iterate: promote reference file content to skill.md wherever evals reveal skipping
If an eval shows the agent missed guidance that was in a reference file, move it into skill.md. Do not try to fix this by making reference files more prominent — assume they will be skipped and act accordingly.
- 10
Distribute via repo-bundling and maintain versioning
Package the skill inside the relevant repo (e.g. a .claude or .cursor directory). Treat the skill as a versioned artifact — new versions for major changes, same as software. Note that a universal skill registry/package manager is an unsolved distribution problem; repo-bundling is currently the most reliable pattern.
// What are real-world examples of the Rodrigues method in action?
A backend platform that uses a database with row-level security. Agents creating SQL views consistently bypass the security policy because they omit a required flag, exposing data that should be protected.
The security flag requirement (e.g. 'security invoker = true' equivalent for the platform) is classified as a non-negotiable, non-skippable rule. It is placed directly in skill.md — not in a reference file — as part of a security checklist section. The eval is written to specifically test whether the agent sets this flag correctly when creating views over secured tables. Baseline and MCP-only conditions are expected to fail; MCP + skill is expected to pass. If the agent still misses it, the language in skill.md is strengthened with more explicit instruction.
A developer platform wants agents to manage database schema changes without creating redundant migration files on every small edit, which causes version control noise and deployment issues.
An opinionated workflow is encoded directly in skill.md: (1) make schema changes freely on the development environment, (2) run the platform's advisor tool to surface security and performance issues, (3) fix all flagged issues, (4) only then generate the migration file. The skill explicitly instructs agents NOT to generate a migration file on each incremental change. This workflow is presented as the platform's recommended approach, giving the agent both the rule and the rationale.
A platform team wants agents to always use up-to-date API documentation rather than hallucinating deprecated endpoints from training data.
The skill.md contains a persistent, emphatic directive instructing the agent to fetch live documentation before attempting any API interaction, rather than relying on training data. The instruction is framed as a hard requirement, not a suggestion. The skill provides the exact mechanism for accessing live docs (URL pattern, file system interface, or search tool) and repeats the fetch-first instruction at multiple relevant points in the skill file to counteract the agent's default laziness toward tool calls.
// What mistakes should I avoid when building a skill.md with this method?
- Putting non-negotiable safety or correctness rules in reference files — agents will skip them. If the agent missing the information would cause an incorrect or unsafe outcome, it must be in skill.md directly.
- Duplicating documentation content inside the skill instead of pointing agents to the live single source of truth — this creates a maintenance burden and the skill will go stale.
- Being neutral and non-opinionated about workflows — failing to encode the specific sequences you know work best leaves agents to infer workflows from general training, which produces suboptimal or incorrect results.
- Over-populating the skill.md on the first version — starting large makes it harder to isolate what is and isn't working. Start minimal, run evals, then expand.
- Testing the skill against only one model — a skill that works for one model family may fail on another. Agent-agnostic performance requires multi-model eval coverage.
- Assuming agents will load more than one reference file for a single task — design for the reality that agents will rarely load two reference files and almost never load three or more.
- Neglecting evals entirely — without a graded, scenario-based test suite run across baseline, MCP-only, and MCP+skill conditions, you have no reliable way to know whether the skill is actually improving agent behaviour.
- Treating skill distribution as solved — there is currently no universal package manager or registry for skills; plan for repo-bundling as the primary distribution mechanism and be explicit about discoverability.
// What key terms do I need to understand for the Rodrigues Product Skill Architecture Method?
- Skill
- A folder containing a skill.md instruction file, optional reference files, and optional bundled scripts, designed to be progressively discovered by agents. The skill gives agents product-specific guidance that their training data does not contain.
- skill.md
- The main instruction file inside a skill folder. This is the primary document the agent loads. Any guidance that cannot be missed must live here — not in reference files.
- Front Matter
- The name and description metadata envelope at the top of a skill file. This is the signal the agent uses to decide whether to load the skill for a given task. Must be written precisely.
- Reference Files
- Optional supplementary files bundled within a skill that skill.md can point to for additional detail. Agents are lazy about loading these — assume they will load at most one per task, and design the skill accordingly.
- Context Gap
- The delta between what an agent knows from training data and what it needs to know to work correctly with a specific, updated, or proprietary product. Skills are the mechanism for closing this gap.
- Evals (Evaluations)
- Automated tests run against an agent's behaviour — analogous to unit tests for code, but evaluating reasoning, tool calls, and output correctness rather than deterministic program output. Used to test skill.md as a document in CI-style conditions.
- Test Completeness Score
- The graded scoring metric used in evals to assess how completely and correctly an agent completed a task scenario. Used to compare performance across baseline, MCP-only, and MCP+skill conditions.
- Single Source of Truth
- The canonical, always-up-to-date documentation for a product. The skill should point agents here rather than reproducing content, with explicit and persistent instructions to fetch from it.
- Opinionated Workflow
- A specific, ordered sequence of operations that the skill author has determined is the most effective way for an agent to accomplish a task on their product. Skills should encode these explicitly rather than leaving sequencing to agent inference.
- Docs-over-SSH
- An interface pattern where product documentation is exposed via SSH, allowing agents to navigate it using familiar file-system and Linux-based tools rather than requiring specialised web-fetching behaviour.
- MCP (Model Context Protocol)
- A protocol enabling agents to call tools and integrations. In this framework, MCP provides the agent's action capabilities (tools), while the skill provides the guidance on how to use those tools correctly for a specific product. They are complementary, not competing.
// FREQUENTLY ASKED QUESTIONS
What is the Rodrigues Product Skill Architecture Method?
It is a framework for creating reusable skill.md documents that bridge the gap between an AI agent's training data and your specific product's requirements. Developed by Pedro Rodrigues of Supabase, it ensures agents follow correct security checks, use up-to-date APIs, and execute workflows in the right order by embedding critical rules directly in the skill file and pointing agents to live documentation rather than duplicating content.
What is a skill.md file and why does it matter for AI agents?
A skill.md is the primary instruction file inside a skill folder that an AI agent loads to get product-specific guidance missing from its training data. It matters because agents default to stale or incorrect behavior without it. Any non-negotiable security checks, opinionated workflows, and documentation-fetching directives must live directly in skill.md since agents will skip supplementary reference files.
How do I build a skill.md using the Rodrigues method?
Start by auditing known agent failure modes with your product. Identify your single source of truth for documentation. Separate must-load content from reference content — critical rules go in skill.md, not reference files. Draft skill.md with precise front matter, non-negotiable checklists, persistent documentation-fetch directives, and opinionated workflows. Add reference files sparingly, then write evals and iterate based on results across multiple models.
How do I write evals for my skill.md?
Create at least six realistic task scenarios covering your known agent failure modes. Run each scenario in three conditions: baseline (no MCP, no skill), MCP only, and MCP plus skill. Score completeness on a graded scale. Test across at least two model families to ensure the skill is agent-agnostic. If agents miss guidance from reference files, promote that content into skill.md and re-run evals.
How does the Rodrigues method compare to just writing better API documentation?
Better API documentation helps humans but doesn't solve the agent context gap. The Rodrigues method specifically addresses how agents process instructions — agents skip reference files, resist tool calls, and default to training data. This method embeds non-skippable rules in skill.md, forces documentation fetching with persistent directives, and validates agent behavior through structured evals, which standard documentation does not do.
When should I use the Rodrigues Product Skill Architecture Method?
Use it whenever AI agents produce stale, unsafe, or workflow-incorrect outputs when working with your product. This is especially critical when your product has security requirements agents might skip, proprietary workflows that differ from common patterns, APIs that have changed since model training cutoffs, or specific operation sequences where incorrect ordering causes failures or data exposure.
What results can I expect after implementing a skill.md with this method?
You can expect measurably improved agent correctness on your product's workflows, validated through graded eval scores. Agents should consistently follow security checklists, use current APIs instead of deprecated ones, and execute operations in the correct order. The improvement should be visible in the delta between baseline, MCP-only, and MCP+skill eval conditions across multiple model families.
Why do agents skip reference files in skill folders?
Agents are inherently lazy about loading additional files — they resist loading more than one reference file and rarely load two or more per task. This is a behavioral pattern across model families, not a bug in any specific model. The Rodrigues method accounts for this by mandating that any guidance the agent absolutely cannot miss must live directly in skill.md, not in supplementary reference files.
What is the context gap in AI agents?
The context gap is the delta between what an AI agent knows from its training data and what it needs to know to work correctly with a specific, updated, or proprietary product. This gap causes agents to use deprecated APIs, miss security requirements, and follow incorrect workflows. Skills built with the Rodrigues method are designed specifically to close this gap.
How does skill.md work with MCP servers?
MCP (Model Context Protocol) provides an agent's action capabilities — tools it can call and integrations it can use. The skill.md provides the guidance on how to use those tools correctly for a specific product. They are complementary: MCP gives the agent hands, and skill.md gives it the knowledge of what to do with them. Evals should test both MCP-only and MCP+skill conditions.