api-documentation_skill

Overview

This skill produces clear, comprehensive API documentation tailored for developer reference. It captures function signatures, parameter types, return values, errors, and working code examples. The goal is fast developer onboarding and reliable API usage guidance.

How this skill works

The skill inspects function or endpoint definitions and generates structured docs that include typed signatures, per-parameter descriptions, return semantics, and a list of possible exceptions. It also crafts minimal, runnable example code and annotates lifecycle notes such as version added or deprecation. Output is concise, consistent, and ready to include in SDK docs or developer portals.

When to use it

• Documenting public or internal APIs for developers
• Creating or updating SDK reference documentation
• Producing example-driven guides for new endpoints
• Recording breaking changes, deprecations, or version notes
• Standardizing docs across services and teams

Best practices

• Include explicit type information for every parameter and return value
• Provide at least one complete, runnable example showing common usage
• List all possible errors and the conditions that trigger them
• Mark version_added and version_deprecated where relevant
• Keep descriptions concise and prioritize developer actions over implementation details

Example use cases

• Document a queue.add_task(title, agent, priority, description) function with sample call and error cases
• Create SDK method docs for REST endpoints returned by automated workflows
• Add parameter and error details for agent task-management APIs
• Produce migration notes showing behavioral changes and deprecation guidance
• Generate language-specific examples (Python) for quick copy-paste by developers