How to Build Agent Skills for Your Developer Platform
For Developer platform teams (e.g., database, auth, or infrastructure platforms) · Based on Rodrigues Product Skill Architecture Method
// TL;DR
If you run a developer platform — a database service, auth provider, or infrastructure product — the Rodrigues Product Skill Architecture Method helps you create skill.md files that prevent agents from skipping security flags, using deprecated APIs, or generating incorrect migration files. It works by embedding non-negotiable rules directly in the skill, pointing agents to your live docs, and encoding opinionated workflows like schema-change-then-lint-then-migrate. Validate everything with multi-model evals comparing baseline, MCP-only, and MCP+skill conditions.
Why do AI agents get my platform's security requirements wrong?
Agents default to their training data, which often predates your latest security model. If your database uses row-level security and requires a specific flag on views — like `security invoker = true` — the agent won't know about it unless explicitly told. Worse, agents skip reference files, so burying this requirement in a supplementary document guarantees it gets missed.
The Rodrigues method solves this by classifying every piece of guidance: if missing it would produce an unsafe outcome, it goes directly into skill.md. Your security checklist lives front and center, not in an optional reference file the agent will ignore.
How do I stop agents from generating redundant migration files?
This is a workflow sequencing problem. Without explicit instruction, agents generate a new migration file on every small schema edit — creating version control noise and deployment headaches.
Encode your opinionated workflow directly in skill.md:
1. Make schema changes freely on the development environment
2. Run your platform's advisor/linter tool to surface security and performance issues
3. Fix all flagged issues
4. Only then generate the migration file
Explain the rationale: generating migrations on every edit creates unnecessary files, and running the advisor after migration is too late to catch issues cheaply. Give the agent both the rule and the reasoning so it has context to anchor on.
How do I make sure agents use my current API, not deprecated endpoints?
Agents hallucinate deprecated endpoints because their training data is stale. The Rodrigues method addresses this with persistent, emphatic documentation-fetching directives.
In your skill.md, state as a hard requirement — not a suggestion — that the agent must fetch your live documentation before any API interaction. Provide the exact mechanism: a URL pattern, a docs-over-SSH path, or a semantic search tool. Repeat this instruction at multiple relevant points in the skill file. Agents resist tool calls by default, so one mention isn't enough.
Pair this with your single source of truth — the canonical, always-up-to-date documentation. The skill points here rather than reproducing content, which eliminates the maintenance burden of keeping the skill in sync with your docs.
How do I validate that my skill actually works?
Write at least six eval scenarios covering your known failure modes — the exact cases where agents previously used deprecated APIs, skipped security flags, or broke workflow ordering. Run each scenario in three conditions:
- Baseline: No MCP, no skill
- MCP only: Tools available, no skill guidance
- MCP + skill: Full setup
Score each run on a graded completeness metric. The delta between conditions proves the skill's value. Test across at least two model families (e.g., Claude and GPT-4) to ensure agent-agnostic performance.
If an eval reveals agents skipping guidance from a reference file, promote that content to skill.md immediately. Don't try to make reference files more prominent — accept they will be skipped and act accordingly.
What's the next step?
Audit your top five agent failure modes today. List the security checks agents miss, the deprecated patterns they use, and the workflows they get out of order. That list becomes your skill.md specification. Start minimal — just the non-negotiable rules — and expand based on eval results.
// FREQUENTLY ASKED QUESTIONS
How long should a skill.md be for a developer platform?
Start as short as possible — only the non-skippable security rules, documentation-fetch directives, and critical workflow sequences. A first version might be 50-100 lines. Expand incrementally based on eval results. If agents consistently follow all guidance, the length is right. If they start ignoring instructions, the skill may be too long and needs pruning.
Can I use one skill.md for my entire platform or do I need separate ones?
Use one skill per major product surface. If your platform has distinct areas (e.g., database, auth, storage) with different security models and workflows, separate skills with precise front matter let agents load only what's relevant. A single monolithic skill risks being too large for agents to process effectively and creates ambiguous front matter.
Do I need to update my skill.md every time I ship a new API version?
No, because the skill points to live documentation rather than reproducing API details. Only update skill.md when security requirements, non-negotiable rules, or recommended workflow sequences change. Routine API additions are covered by the documentation-fetching directive. Version the skill alongside major product releases.