Agent-Skills.md

Agent Skills: 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.

UncategorizedID: aj-geddes/useful-ai-prompts/api-changelog-versioning

Repository

aj-geddes/useful-ai-prompts
aj-geddesLicense: MIT
607

Install this agent skill to your local

pnpm dlx add-skill https://github.com/aj-geddes/useful-ai-prompts/tree/HEAD/skills/api-changelog-versioning

Skill Files

Browse the full folder contents for api-changelog-versioning.

Download Skill

Loading file tree…

skills/api-changelog-versioning/SKILL.md

Skill Metadata

Name
api-changelog-versioning
Description
>

API Changelog & Versioning

Table of Contents

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
# API Changelog

## Version 3.0.0 - 2025-01-15

### 🚨 Breaking Changes

#### Authentication Method Changed

**Previous (v2):**

```http
GET /api/users
Authorization: Token abc123
```

## Reference Guides

Detailed implementations in the `references/` directory:

| Guide | Contents |
|---|---|
| [🚨 Breaking Changes](references/breaking-changes.md) | 🚨 Breaking Changes |
| [✨ New Features](references/new-features.md) | ✨ New Features |
| [🔧 Improvements](references/improvements.md) | 🔧 Improvements |
| [🔒 Security](references/security.md) | 🔒 Security, 🗑️ Deprecated, 📊 Version Support Policy |
| [Step 1: Update Base URL](references/step-1-update-base-url.md) | 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