How DevRel Teams Build Skills That Make Agents Work
For DevRel and developer experience engineers responsible for AI-agent adoption · Based on Rodrigues Product Skill Architecture Method
// TL;DR
As a DevRel or developer experience engineer, you're responsible for how developers — and now their AI agents — experience your product. The Rodrigues method gives you a structured process for building skill.md documents that prevent agents from hallucinating deprecated APIs, skipping security steps, or following incorrect workflows. It treats the skill like testable code: start minimal, run multi-model evals comparing baseline vs. MCP-only vs. MCP+skill, and iterate based on graded completeness scores. The skill ships in your repo and is versioned like any product artifact.
Why is agent experience now part of developer experience?
Developers increasingly interact with your product through AI agents — Cursor, Claude, Copilot, and custom integrations. When an agent gets your product wrong, the developer blames your product, not the agent. Stale API patterns, missed security flags, and incorrect workflow ordering all erode trust in your platform.
The context gap — the delta between agent training data and your current product state — is now a DevRel problem. A skill.md is the tool that closes it.
How do I audit agent failure modes for my product?
This is Step 1 of the Rodrigues method and the foundation for everything else. Work with your support team, community forums, and internal dogfooding to compile a list:
- Stale patterns: Which deprecated endpoints or SDK versions do agents default to?
- Security misses: Which required flags, auth steps, or compliance checks do agents skip?
- Workflow errors: Where do agents execute steps out of order or generate unnecessary artifacts?
- Hallucinations: Where do agents invent features or parameters that don't exist?
Each failure becomes an eval scenario. Each eval scenario validates a specific piece of skill.md guidance. This is how you turn anecdotal "agents keep getting X wrong" into measurable, improvable results.
How do I write a skill.md that agents actually follow?
Apply the core Rodrigues principles:
Don't duplicate information. Your skill.md points to your live documentation — it doesn't reproduce it. Include a persistent, repeated directive: "Fetch live documentation from [URL/path] before any API interaction. Do not rely on training data." Be emphatic. Agents resist tool calls, so one mention isn't enough.
If it can be skipped, it will be skipped. Every non-negotiable rule — security checklists, required flags, auth steps — goes directly in skill.md. Reference files are for supplementary detail only. Agents load at most one reference file per task. If a rule matters, it cannot live in a reference file.
Be opinionated. Encode your recommended workflows as explicit numbered sequences with rationale. Don't say "consider running the linter" — say "Step 2: Run the advisor tool. Step 3: Fix all flagged issues. Step 4: Only then generate the migration. This order prevents security issues from reaching production."
Start minimal. Your first skill.md should contain only the most critical guidance. Run evals, see what agents miss, and expand accordingly. The instinct to front-load everything is a trap — oversized skills cause agents to deprioritize instructions.
How do I test and iterate on my skill?
Create eval scenarios for each failure mode — aim for at least six. Structure your testing:
| Condition | What's available | Expected result |
|-----------|-----------------|----------------|
| Baseline | No MCP, no skill | Fails on known failure modes |
| MCP only | Tools available, no guidance | Partial improvement |
| MCP + skill | Full setup | Passes all critical checks |
Score on a graded completeness metric, not pass/fail. Test across at least two model families. A skill that only works on Claude isn't production-ready.
Critical iteration rule: if an eval shows an agent missed guidance that was in a reference file, promote it to skill.md immediately. Don't try to make reference files more discoverable — accept they will be skipped.
How do I ship and maintain the skill?
Bundle the skill folder in your repo's `.claude` or `.cursor` directory. Version it alongside your product. Document its existence in your README and quickstart guides.
Treat major skill updates like releases: increment the version, re-run evals, and communicate changes to your developer community. The skill is now part of your developer experience surface — maintain it with the same rigor as your SDK or CLI.
What's the next step?
Pull your last 20 support tickets or community questions where an AI agent got your product wrong. Categorize them into stale patterns, security misses, and workflow errors. That categorized list is your skill.md specification. Draft the first version today — just the top three non-negotiable rules — and run a basic eval this week.
// FREQUENTLY ASKED QUESTIONS
How do I convince my team that skill.md is worth the investment?
Run a baseline eval showing how agents currently fail with your product — deprecated APIs used, security flags skipped, wrong workflow ordering. Then build a minimal skill.md addressing the top three failures and re-run the eval. The graded completeness score delta between baseline and MCP+skill is your business case. Quantified improvement in agent behavior directly maps to fewer support tickets and better developer adoption.
Should the DevRel team or the engineering team own the skill.md?
DevRel should own the skill.md because it's a developer experience artifact, but engineering must provide the inputs — especially the non-negotiable security requirements and correct workflow sequences. Treat it like API documentation: product engineering defines what's correct, DevRel ensures it's communicated effectively to agents. Evals should run in CI, jointly owned.
How do I handle skill.md for a product with multiple SDKs and languages?
Create one core skill.md with language-agnostic rules (security checklists, workflow sequences, documentation-fetch directives). Use reference files for language-specific patterns, but remember agents rarely load them. If a language-specific pattern is critical (e.g., a required flag syntax differs between Python and JavaScript), include the most common variants directly in skill.md.