How Do API Product Managers Make AI Agents Use Their API Correctly?
For API product managers · Based on Rodrigues Product Skill Architecture Method
// TL;DR
API product managers face a specific problem: AI agents hallucinate deprecated endpoints, ignore authentication requirements, and call APIs in incorrect sequences. The Rodrigues Product Skill Architecture Method gives PMs a framework to build skill.md documents that force agents to fetch live API documentation, follow prescribed calling patterns, and never skip security requirements. Instead of hoping agents get it right from training data, PMs encode the correct behavior as testable, versioned instruction documents bundled with their API's repository.
Why Do AI Agents Hallucinate Your API Endpoints?
When a developer asks an AI agent to integrate with your API, the agent reaches into its training data — which may be months or years out of date. The result: hallucinated endpoints that no longer exist, deprecated parameter formats, missing authentication headers, and API calls in sequences that violate your platform's business logic.
This isn't a model intelligence problem. It's a context gap problem. The agent simply doesn't have access to your current API surface.
The Rodrigues Product Skill Architecture Method solves this by creating a skill.md — a structured instruction document that closes the gap between training data and your live API.
What Should an API Product Manager Include in a Skill.md?
As a PM, you own the knowledge of how your API should be used. The skill.md is where you encode that knowledge for AI agents. Focus on three categories:
1. Non-negotiable requirements — these go directly in skill.md, never in reference files. Examples:
- Authentication must use OAuth 2.0 with PKCE flow, not API keys
- All write operations require an idempotency key header
- Rate limits apply per-organization, not per-user — agents must implement exponential backoff
2. Persistent fetch-docs directives — instruct the agent emphatically and repeatedly to check your live API reference before making any call. Provide the exact URL or access mechanism. Be stubborn: repeat this instruction at multiple points in the skill because agents default to training data over tool calls.
3. Opinionated calling sequences — for multi-step operations, define the correct order explicitly. If creating a resource requires first validating the schema, then creating a draft, then publishing — write that sequence in the skill with rationale for each step.
How Do You Test Whether Agents Follow Your Skill?
Build an eval suite with at least six realistic API integration scenarios. Include your most common failure modes:
- Agent tries to call a v1 endpoint that was replaced by v2
- Agent omits the required authentication header
- Agent calls endpoints out of sequence, causing a 409 conflict
- Agent uses a deprecated parameter format
Run each scenario three ways: baseline (no skill, no tools), with MCP tools only, and with MCP plus your skill.md. Score on a graded completeness scale. The skill should produce measurably better API usage.
Critically, test across multiple models. If your skill works on Claude but fails on GPT-4, the skill's language needs strengthening — not the model.
How Do You Keep the Skill Current as Your API Evolves?
Version your skill.md alongside your API. When you deprecate an endpoint, add a directive to skill.md. When you add a new required header, add it to the non-negotiable checklist. When you change a workflow sequence, update the opinionated workflow section.
The skill should never duplicate your full API reference — it points agents to your live docs for details. But the rules, sequences, and fetch-docs directives must stay current. Re-run your eval suite after every skill update to catch regressions.
Bundle the skill in your API's SDK repository or developer toolkit. Treat it as a first-class artifact: reviewed, versioned, and tested.
What's Your Next Step?
List the top five ways AI agents currently misuse your API. That list is the specification for your first skill.md. Draft it with just those five rules, write three eval scenarios, and run them. You'll have data within a day on whether the skill improves agent behavior — and a foundation to iterate from.
// FREQUENTLY ASKED QUESTIONS
How do I stop agents from using deprecated API endpoints?
Include a persistent directive in skill.md instructing the agent to fetch your live API reference before any call — frame this as a hard requirement, not a suggestion. Provide the exact URL or access mechanism. Repeat this instruction at multiple points in the skill to counteract the agent's tendency to default to training data. Combine this with explicit deprecation notes for commonly confused endpoints in the skill's non-negotiable section.
Should I put my full API reference in the skill.md?
No. The Rodrigues method explicitly prohibits duplicating documentation inside the skill. Duplication creates a maintenance burden and the skill will go stale. Instead, point agents to your live API reference as the single source of truth. Skill.md contains only the rules, workflows, and directives that aren't captured in standard documentation — non-negotiable security requirements, calling sequences, and the instruction to always fetch live docs first.
How do I handle API versioning in a skill.md?
Version your skill alongside your API. When a major API version changes, create a new skill version. Include explicit directives about which API version agents should target and how to detect the correct version. If multiple API versions coexist, encode the decision logic in skill.md — for example, 'Use v3 for all new integrations; v2 is deprecated and will be removed on [date].' Run evals against both versions during migration periods.