api-documentation

Document APIs comprehensively with signatures, parameters, return values, errors, and working code examples for developer reference

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️2downloads

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

  1. Signature Documentation - Clear parameter and return type descriptions
  2. Example Creation - Practical, working code examples
  3. Error Documentation - All possible errors and when they occur

Approach

  1. Document function signature with types
  2. Describe each parameter clearly
  3. Describe return value and possible states
  4. List all exceptions/errors that can be raised
  5. Provide working example code
  6. 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