Write API documentation with AI
Build a reference that explains the success case, the limits and what the caller can do when a request fails.
Write API documentation with AI when a generated list of fields leaves callers guessing what happens in practice. The api-documentation skill helps an agent ground the reference in interface definitions, then add meaning, defaults, failure behaviour and complete examples that can be checked against the implementation.
Consider a list of orders. A caller needs to distinguish an empty result from an invalid filter, find the next page and know when to retry. A clear reference makes each of those cases discoverable from the relevant operation rather than scattering them across tutorials.
What it does
- Explain required fields and the effect of omitting optional ones.
- Show one complete request and the response it produces.
- Give each documented error a likely cause and recovery action.
- Describe pagination, rate limits and repeat requests where applicable.
- Check examples when a public interface changes.
Install and use
- Use an agent with authorised source definitions or a specification and access to a test endpoint. Use scoped credentials for authenticated examples.
- Ask it to document one operation, including an empty result and a realistic failure.
- Run the example against the intended test version and compare the result with the page.
FAQ
Source
Made by Arjun Prabhulal. Original skill: api-documentation, published on GitHub under the MIT licence.
View on GitHub