Two Approaches to Helping AI Agents Use Your API (And Why You Need Both)

AI coding agents often encounter predictable issues when interacting with APIs, primarily due to two failure modes: the "known unknowns," where agents lack specific insights that API maintainers have, and the "unknown unknowns," which involve environmental specifics not covered by documentation. Mintlify's SKILL.md and Armin Ronacher's REPL-first MCP address these issues by complementing each other, with SKILL.md providing a briefing that prevents known mistakes and the REPL allowing agents to discover current system states. This dual approach ensures agents are better equipped to write correct code by handling static knowledge and dynamic discovery, although it doesn’t completely eliminate failures. Instead, it shifts the focus from avoidable, mundane errors to more nuanced challenges. While SKILL.md packages accumulated product intuition, the REPL enables real-time exploration, and together they guide agents in making informed decisions without relying solely on documentation, ultimately improving the developer experience.