Rodrigues Product Skill Architecture Method

Last updated: 20 May 2026

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 agent skill documents (skill.md files) that close the context gap between an AI agent's training data and your specific product's current APIs, security requirements, and workflows. Use it whenever agents produce stale, unsafe, or workflow-incorrect outputs when interacting with your product or platform. The method teaches you to separate must-load content from reference files, encode opinionated workflows, point agents to live documentation instead of duplicating it, and validate everything with graded evals across multiple models.

Framework

// 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 with 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 behind 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 Product Skill Architecture 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 product skill 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 are the key terms and concepts in 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 give AI agents the product-specific context they lack from training data. Developed by Pedro Rodrigues of Supabase, the method closes the 'context gap' by encoding non-negotiable security rules, opinionated workflows, and persistent directives to fetch live documentation — all structured so agents actually follow them. It complements MCP tool integrations by providing the guidance layer on how to use those tools correctly.

What is a skill.md file and why do agents need one?

A skill.md file is the primary instruction document inside a skill folder that agents load for product-specific guidance. Agents need one because their training data is stale, incomplete, or missing proprietary knowledge about your product. The skill.md contains non-negotiable security checks, opinionated workflows, and persistent directives to fetch live docs. Anything the agent absolutely cannot miss must live here, not in reference files, because agents will skip supplementary files.

How do I build a skill.md for my product?

Start by auditing every known way agents get your product wrong — missed security steps, stale APIs, incorrect sequencing. Then identify your canonical documentation URL as the single source of truth. Classify all guidance: non-skippable rules go directly into skill.md, everything else goes into optional reference files. Draft the skill.md with precise front matter, core instructions, persistent fetch-docs directives, and explicit opinionated workflows. Start minimal, write evals, and iterate by promoting reference content when evals show agents skip it.

How do I write evals for a skill.md?

Create at least six realistic task scenarios covering your known agent failure modes. Run each scenario under three conditions: baseline (no MCP, no skill), MCP-only, and MCP plus skill. Score each run with a graded completeness metric. Test across at least two model families to confirm the skill is agent-agnostic. If a reference file's content gets skipped, move it into skill.md. Treat skill.md testing with the same rigor as testing code — these evals are your CI pipeline for documentation.

How does the Rodrigues method compare to just writing good documentation?

Good documentation is necessary but not sufficient. The Rodrigues method doesn't replace your docs — it explicitly points agents to them while adding a guidance layer docs alone cannot provide. Regular documentation is passive; skill.md is an active instruction set that tells agents what to never skip, which workflow order to follow, and when to fetch live information instead of relying on training data. It also includes eval infrastructure to verify agents actually follow the guidance, which static documentation cannot do.

When should I use the Rodrigues Product Skill Architecture Method?

Use it whenever AI agents produce incorrect, stale, or unsafe outputs when working with your product. Specific triggers include: agents using deprecated API endpoints, missing required security flags like row-level security, generating redundant migration files, or following incorrect workflow sequences. It is especially critical for products with security requirements, proprietary workflows, or knowledge that post-dates model training data. If agents are getting your product wrong, you need a skill.

What results can I expect after implementing a skill.md?

You can expect measurably improved agent behavior on your product's tasks, validated through graded eval scores. Specifically, agents should correctly follow security checklists they previously missed, use current APIs instead of deprecated ones, follow your prescribed workflow sequences, and fetch live documentation rather than hallucinating. In the Supabase case study, MCP plus skill conditions consistently outperformed both baseline and MCP-only conditions across multiple models, with the most dramatic improvements on security-critical tasks.

What's the difference between skill.md and reference files?

Skill.md is the main instruction file that agents always load — it contains non-negotiable rules, security checklists, and opinionated workflows. Reference files are optional supplementary documents for single sub-topics. The critical distinction: agents are lazy about loading reference files and will rarely load more than one per task. If missing a piece of guidance would produce an incorrect or unsafe outcome, it must be in skill.md directly. Reference files are for genuinely optional detail only.

How does skill.md work with MCP servers?

Skill.md and MCP are complementary, not competing. MCP provides the agent's action capabilities — the tools it can call to interact with your product. Skill.md provides the guidance on how to use those tools correctly, safely, and in the right order. Without a skill, an agent with MCP tools will still miss security steps, follow incorrect workflows, and use stale patterns. The skill is the intelligence layer that makes tool usage effective for your specific product.

Can I use one skill.md across different AI models?

Yes, and you should. The Rodrigues method requires testing your skill across at least two model families to confirm it is agent-agnostic. A skill that only works for one model is fragile. If a model fails where others pass, strengthen the skill.md language to accommodate that model's tendencies. Design the skill for broad compatibility by using clear, explicit instructions rather than relying on model-specific prompting tricks.

How do I distribute a skill.md to developers?

Bundle the skill inside the relevant repository — for example, in a .claude or .cursor directory. Treat the skill as a versioned artifact with new versions for major changes, just like software releases. There is currently no universal package manager or registry for agent skills; repo-bundling is the most reliable distribution pattern available. Be explicit about discoverability by documenting the skill's location and purpose in your project's README or contributing guide.

// GET STARTED

Turn Any YouTube Video Into An AI Skill

SkillForge captures a creator's exact methodology from their video and turns it into a reusable AI skill you can invoke in Claude, ChatGPT, or any LLM.

Forge your own skill