This skill provides comprehensive documentation capabilities including API documentation, technical writing, changelog generation, and developer guides. It covers everything from OpenAPI specifications to user-facing changelogs.
When to Use This Skill
When documenting REST APIs or GraphQL schemas
When creating OpenAPI/Swagger specifications
When generating client SDKs
When writing API integration guides
When creating interactive API documentation
When maintaining API versioning and migration guides
When writing user guides and tutorials
When creating or improving README files
When documenting architecture and design decisions
When writing code comments and inline documentation
When improving content clarity and accessibility
When creating getting started documentation
When writing feature specifications and design documents
When creating Architecture Decision Records (ADRs)
When documenting technical decisions and their rationale
When creating migration guides for version upgrades
When documenting breaking changes and upgrade paths
When planning and documenting database migrations
When preparing release notes for a new version
When creating weekly or monthly product update summaries
When documenting changes for customers
When writing changelog entries for app store submissions
When generating update notifications
When creating internal release documentation
When maintaining a public changelog/product updates page
SDK Generation: Generates client libraries and SDKs
Interactive Docs: Creates Postman collections and interactive docs
Versioning: Manages API versioning and migration guides
Code Examples: Provides examples in multiple languages
Developer Guides: Writes authentication and integration guides
User Guides: Creates step-by-step user guides with clear instructions
Tutorials: Writes progressive tutorials that build knowledge
README Files: Creates comprehensive README files with badges and sections
10. Architecture Docs: Documents system architecture and design decisions
11. Code Documentation: Writes clear code comments and inline docs
12. Content Organization: Structures content with clear headings and flow
13. Changelog Generation: Transforms git commits into user-friendly changelogs
14. Design Specs: Creates feature specifications and technical design documents
15. ADRs: Documents Architecture Decision Records with context and consequences
16. Migration Guides: Creates step-by-step migration documentation with rollback procedures
How to Use
Document API
Create OpenAPI specification for this API
Generate API documentation for the /api/users endpoints
Write Documentation
Create a user guide for this feature
Write a README for this project
Generate Changelog
Create a changelog from commits since last release
Generate changelog for all commits from the past week
API Documentation
Document as You Build
Document APIs during development, not after
Keep documentation in sync with code
Use real examples over abstract descriptions
Show both success and error cases
Version everything including docs
OpenAPI Specification
Structure:
API metadata (title, version, description)
Server definitions
Security schemes
Paths and operations
Request/response schemas
Examples for all operations
Example:
openapi: 3.0.0
info:
title: User API
version: 1.0.0
description: API for user management
paths:
/users:
get:
summary: List users
responses:
'200':
description: List of users
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
SDK Generation
Supported Languages:
JavaScript/TypeScript
Python
Java
Go
Ruby
PHP
Tools:
OpenAPI Generator
Swagger Codegen
SDK generators
Code Examples
Provide examples in multiple languages:
JavaScript/Node.js
Python
cURL
Ruby
Java
Technical Writing
Write for Your Audience
Know their skill level
Use appropriate terminology
Provide context when needed
Assume minimal prior knowledge
Include troubleshooting sections
Lead with the Outcome
Start with what users will accomplish
Show the value before the steps
Use clear, action-oriented language
Focus on user success, not features
Use Active Voice
Prefer active over passive voice
Use clear, concise language
Avoid jargon when possible
Include real examples and scenarios
Test instructions by following them exactly
Documentation Types
User Guides:
Overview and goals
Prerequisites
Step-by-step instructions
Screenshots or examples
Troubleshooting
Next steps
README Files:
Project title and description
Badges (build status, version, license)
Features
Installation
Quick start
Usage examples
Contributing
License
Architecture Docs:
System overview
Component diagrams
Design decisions
Technology choices
Integration points
Data flow
Changelog Generation
Transforming Git Commits
Automatically creates user-facing changelogs from git commits by:
Transforming technical commits into clear, customer-friendly release notes
Filtering out internal commits (refactoring, tests, etc.)
Basic Usage
Create a changelog from commits since last release
Generate changelog for all commits from the past week
Create release notes for version 2.5.0
With Specific Date Range
Create a changelog for all commits between March 1 and March 15
With Custom Guidelines
Create a changelog for commits since v2.4.0, using my changelog
guidelines from CHANGELOG_STYLE.md
Example Output
# Updates - Week of March 10, 2024
## ✨ New Features
- **Team Workspaces**: Create separate workspaces for different
projects. Invite team members and keep everything organized.
- **Keyboard Shortcuts**: Press ? to see all available shortcuts.
Navigate faster without touching your mouse.
## 🔧 Improvements
- **Faster Sync**: Files now sync 2x faster across devices
- **Better Search**: Search now includes file contents, not just titles
## 🐛 Fixes
- Fixed issue where large images wouldn't upload
- Resolved timezone confusion in scheduled posts
- Corrected notification badge count
Reference Files
For detailed documentation patterns and guidance, load reference files as needed:
references/api_docs.md - API documentation patterns, OpenAPI specifications, SDK generation, versioning strategies, and code examples
references/technical_writing.md - Technical writing best practices, user guide structure, README templates, architecture documentation, and content organization
references/changelogs.md - Changelog generation patterns, commit categorization, user-friendly transformation, and release note best practices
references/API_DOCUMENTATION.template.md - REST API documentation template with endpoints, authentication, webhooks, and SDK examples
references/CHANGELOG.template.md - Changelog template following Keep a Changelog format with SemVer
references/DESIGN_SPEC.template.md - Design specification template for feature planning, technical design, and implementation approach
references/ARCHITECTURE_DECISION_RECORD.template.md - ADR template for documenting significant architectural decisions with context and consequences
references/MIGRATION_GUIDE.template.md - Migration guide template for version upgrades, breaking changes, and upgrade paths
When working on specific documentation types, load the appropriate reference file.
Best Practices
Documentation Quality
Real Examples: Use actual working examples, not placeholders
Error Cases: Document error responses with examples