Agent skill · writing content · aj-geddes
api-changelog-versioning
Document API changes, breaking changes, migration guides, and version history for APIs. Use when documenting API versioning, breaking changes, or creating API migration guides.
Why this skill is useful
Codifies best practices for documenting API changes and versioning that the AI could infer but now doesn't have to guess.
What it needs
About 1k tokens when loaded. Last updated 2026-03-04. 307 stars on the source repository.
What this skill does
API Changelog & Versioning Table of Contents Overview When to Use Quick Start Reference Guides Best Practices Overview Create comprehensive API changelogs that document changes, deprecations, breaking changes, and provide migration guides for API consumers. When to Use API version changelogs Breaking changes documentation Migration guides between versions Deprecation notices API upgrade guides Backward compatibility notes Version comparison Quick Start Version comparison http GET /api/users Authorization: Token abc123 Reference Guides Detailed implementations in the references/` directory: Guide Contents --- --- 🚨 Breaking Changes 🚨 Breaking Changes ✨ New Features ✨ New Features 🔧 Improvements 🔧 Improvements 🔒 Security 🔒 Security, 🗑️ Deprecated, 📊 Version Support Policy Step 1: Update Base URL Step 1: Update Base URL, Step 2: Migrate Authentication, Step 3: Update Response Parsing, Step 4: Update Error Handling (+2 more) Best Practices ✅ DO Clearly mark breaking changes Provide migration guides with code examples Include before/after comparisons Document deprecation timelines Show impact on existing implementations Provide SDKs for major versions Use semantic versioning Give advance notice (3-6 months) Maintain backward compatibility when possible Document version support policy ❌ DON'T Make breaking changes without notice Remove endpoints without deprecation period Skip migration examples Forget to version your API Change behavior without documentation Rush deprecations
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aj-geddes/api-changelog-versioning