Frequently Asked Questions About Rodrigues Product Skill Architecture Method
21 answers covering everything from basics to advanced usage.
// Basics
What is the difference between a skill.md and a system prompt?
A skill.md is a product-specific instruction document that agents progressively discover and load based on task relevance, guided by front matter metadata. A system prompt is set at conversation initialization and applies to all interactions. Skills are modular, versioned, and distributed via repos, while system prompts are monolithic. The Rodrigues method treats skills as composable artifacts that complement system prompts rather than replace them.
What is front matter in a skill.md and why is it important?
Front matter is the name and description metadata at the top of a skill.md file. It serves as the signal the agent uses to decide whether to load the skill for a given task. If the front matter is vague or poorly written, agents may not activate the skill when needed or may load it for irrelevant tasks. Writing precise front matter is critical — it functions like a skill's discoverability layer.
Can I use the Rodrigues method for internal tools that aren't publicly documented?
Yes, the method works for internal tools. Your single source of truth can be an internal wiki, a docs-over-SSH interface, or any documentation the agent can access at runtime. The key constraint is that the agent must be able to fetch live information from your source of truth. For fully air-gapped environments, you may need to embed more content directly in skill.md, but still avoid duplicating entire documentation.
Can I use this method if my product doesn't have an MCP server?
Yes. While MCP tools enhance agent capabilities, a skill.md is valuable independently. It closes the context gap by providing correct workflows, security requirements, and documentation-fetching directives regardless of whether MCP is involved. Your evals would compare baseline versus skill-only conditions instead of the three-condition setup. The method's core principles — don't duplicate, be opinionated, start minimal — apply with or without MCP.
What is a test completeness score in the context of skill evals?
A test completeness score is a graded metric that assesses how completely and correctly an agent finished a task scenario. Unlike pass/fail, it captures partial credit — an agent that follows the right workflow but misses one security flag scores higher than one that uses deprecated APIs entirely. This granularity is essential for comparing performance across baseline, MCP-only, and MCP+skill conditions and identifying exactly where the skill adds value.
// How To
How do I decide what goes in skill.md versus a reference file?
Apply the principle: if the agent missing this information would cause an incorrect or unsafe outcome, it must go in skill.md. Security checklists, non-negotiable flags, and critical workflow sequences always go in skill.md. Reference files are for supplementary detail that is genuinely optional for most tasks. If evals show agents skipping important reference file content, promote it to skill.md immediately.
How do I write the documentation-fetching directive in skill.md?
Write it as a hard requirement, not a suggestion. State explicitly that the agent must fetch live documentation before attempting any API interaction and must not rely on training data. Provide the exact mechanism — URL pattern, SSH path, or search tool name. Repeat this instruction at multiple relevant points in the skill file. Agents resist tool calls by default, so persistent, emphatic repetition is necessary to override their laziness.
How do I structure opinionated workflows in my skill.md?
Write each workflow as a specific ordered sequence of numbered steps. Do not leave sequencing implicit. Include the rationale for why each step precedes the next — this gives the agent reasoning to anchor on, not just rules. Example structure: perform schema change → run advisor tool → fix flagged issues → only then generate migration. Explain that skipping the advisor step risks security or performance problems.
How do I set up the three-condition eval for my skill?
Create identical task scenarios and run each one three times: first with no MCP and no skill (baseline), then with MCP tools only, then with MCP plus skill.md loaded. Score each run on a graded completeness metric. The delta between conditions reveals exactly what value the skill adds. If MCP+skill doesn't significantly outperform MCP-only, your skill needs stronger or more specific instructions.
How many reference files can I include in a skill folder?
There is no hard technical limit, but design for the reality that agents will load at most one reference file per task and almost never load two or more. Each reference file should be self-contained for a single sub-topic. Link to them from skill.md with clear conditions for when each should be loaded. If you find yourself creating more than three or four, reconsider whether some content should be fetched from live documentation instead.
// Troubleshooting
What if my skill.md works for Claude but fails for GPT-4?
This indicates the skill's language may rely on tendencies specific to one model family. Investigate which instructions the failing model ignores — it may need more explicit, repeated directives or differently structured reasoning. Strengthen the language for the weakest model without breaking it for others. A skill that only works on one model is fragile and should not be considered production-ready. Multi-model eval coverage is non-negotiable.
What do I do when agents still miss a rule that's already in skill.md?
First, check if the rule is buried among too many other instructions — agents may deprioritize it. Try moving it higher in the file, making the language more emphatic, or repeating it at the specific workflow point where it applies. If the skill.md is already large, consider whether you've violated the start-minimal principle. Test the strengthened version in evals to confirm the fix actually works before shipping.
How do I handle a skill.md that keeps growing too large?
Revisit the start-minimal principle. Audit each section: is this truly non-skippable, or is it duplicating documentation that should be fetched live? Remove anything the agent can retrieve from your single source of truth at runtime. If the skill is still large, consider splitting into multiple focused skills with precise front matter so agents only load the relevant one per task, rather than one monolithic skill.
What happens if I put everything in skill.md and use no reference files?
If every piece of guidance is genuinely non-skippable, this is acceptable — but it risks creating an oversized skill that agents may not fully process. The Rodrigues method recommends starting minimal. If your skill.md grows beyond what agents consistently follow, you've likely included supplementary content that should either be in a reference file or fetched from live documentation. Use eval results to identify the right boundary.
// Comparisons
How does the Rodrigues method compare to RAG for giving agents product context?
RAG retrieves relevant documentation chunks at query time, while a skill.md provides structured, opinionated guidance that includes workflows, security checklists, and behavioral directives — not just information retrieval. The Rodrigues method complements RAG: the skill tells the agent how to work with your product, while RAG or live documentation provides the what. RAG alone doesn't encode workflow sequences or non-negotiable rules the way skill.md does.
How is the Rodrigues method different from just using tool descriptions in MCP?
MCP tool descriptions tell agents what a tool does and its parameters, but they don't encode multi-step workflows, security checklists, or the rationale for specific operation ordering. The Rodrigues method's skill.md provides the strategic layer — it tells agents when and in what order to use tools, what checks to perform between tool calls, and what patterns to avoid. MCP and skills are complementary: tools provide capability, skills provide guidance.
// Advanced
How often should I update my skill.md?
Treat skill.md as a versioned artifact — update it when your product's APIs, security requirements, or recommended workflows change materially. Because the skill points to live documentation rather than duplicating it, routine documentation updates don't require skill changes. Major updates should increment the skill version, just like software releases. Re-run evals after each update to confirm the new version doesn't regress on previously passing scenarios.
What is docs-over-SSH and when should I use it for my skill?
Docs-over-SSH is an interface pattern where product documentation is exposed via SSH, allowing agents to navigate it using familiar file-system and Linux-based tools. Use it when your agents operate in terminal-based environments where HTTP fetching is cumbersome or when you want agents to explore documentation hierarchically. It's an alternative to URL-based doc access and can be specified in your skill.md as the preferred mechanism for fetching live information.
How do I distribute my skill.md to users and teams?
Currently, repo-bundling is the most reliable distribution pattern — package the skill inside a directory like .claude or .cursor in your product's repository. There is no universal skill registry or package manager yet; this is an unsolved distribution problem. Be explicit about where the skill lives in your repo and document its presence in your README. Version the skill alongside your codebase for traceability.
Should I include example prompts in my skill.md?
Only if they encode critical workflow patterns the agent must follow. Generic example prompts add bulk without value — they duplicate what the agent can infer from clear instructions. However, if a specific prompt structure triggers correct behavior that plain instructions don't achieve, include it as a workflow example. Keep it minimal and test via evals whether the example actually improves agent performance before committing it to the skill.
Can I use the Rodrigues method for multiple products in one skill?
No — each skill should target a single product or platform. Combining multiple products in one skill.md creates ambiguous front matter, making it harder for agents to decide when to load the skill. It also inflates the file size unnecessarily. Create separate skills for each product with precise front matter, and let the agent's skill-discovery mechanism load the relevant one based on the task context.