api-documentation
Document APIs comprehensively with signatures, parameters, return values, errors, and working code examples for developer reference
When & Why to Use This Skill
This Claude skill automates the creation of professional-grade API documentation, transforming raw code structures into comprehensive developer references. It specializes in generating detailed function signatures, parameter definitions, return states, and robust error handling guides. By providing functional, ready-to-use code examples, the skill significantly improves developer experience (DX), reduces integration friction, and ensures technical documentation remains accurate and SEO-friendly.
Use Cases
- Public API Portals: Generating high-quality, user-facing documentation for external developers to facilitate rapid platform adoption.
- Internal SDK Reference: Maintaining consistent and up-to-date documentation for internal microservices and shared libraries to streamline team collaboration.
- Legacy Code Onboarding: Creating clear documentation for undocumented legacy systems to help new engineers understand complex API behaviors quickly.
- API Versioning Updates: Automatically updating documentation to reflect changes in parameters, deprecated features, or new error codes during software releases.
| name | "API Documentation" |
|---|---|
| description | "Document APIs comprehensively with signatures, parameters, return values, errors, and working code examples for developer reference" |
| category | "documentation" |
| required_tools | ["Read", "Write", "Grep", "Glob"] |
API Documentation
Purpose
Create comprehensive API documentation that enables developers to quickly understand and correctly use APIs, including parameters, return values, errors, and practical examples.
When to Use
- Documenting public APIs
- Creating developer references
- Writing SDK documentation
- Updating API changes
Key Capabilities
- Signature Documentation - Clear parameter and return type descriptions
- Example Creation - Practical, working code examples
- Error Documentation - All possible errors and when they occur
Approach
- Document function signature with types
- Describe each parameter clearly
- Describe return value and possible states
- List all exceptions/errors that can be raised
- Provide working example code
- Note version added or deprecated
Example
Context: Documenting a task creation function
### add_task(title, agent, priority, description)
Creates a new task in the queue.
**Parameters**:
- `title` (string) - Short descriptive title for the task
- `agent` (string) - Agent name to assign (must exist in agents.json)
- `priority` (string) - One of: "critical", "high", "normal", "low"
- `description` (string) - Detailed task description
**Returns**:
- `string` - Unique task ID for the created task
**Raises**:
- `ValueError` - If agent name is invalid or priority is unknown
- `FileNotFoundError` - If queue file cannot be accessed
**Example**:
```python
task_id = queue.add_task(
title="Fix login bug",
agent="implementer",
priority="high",
description="Users cannot log in with valid credentials"
)
print(f"Created task: {task_id}")
```
**Since**: v1.0.0
Best Practices
- ✅ Include type information for all parameters
- ✅ Provide complete, working examples
- ✅ Document all possible errors
- ❌ Avoid: Incomplete or outdated examples