| name | changelog-generator |
| description | Analyzes commit history, PR descriptions, and spec changes to automatically generate developer-friendly API changelogs. |
Changelog Generator Protocol
This skill bridges the gap between raw git history and consumer-facing API updates. Consumers don't care about "Refactored user service;" they care about "The /users endpoint now returns a profile_pic URL."
Core assumption: A changelog is a communication tool, not a git dump. It must focus on the API interface, not internal implementation tweaks.
1. Input Analysis (Static)
Parse the provided text (Git commits, PR bodies, or OpenAPI diffs) and filter out internal noise.
- Keep: Added fields, new endpoints, deprecated endpoints, bug fixes that changed API behavior.
- Discard: Dependency updates, CI/CD tweaks, internal refactoring (unless it drastically improved performance).
2. Categorization & Formatting
Organize the update into established categories:
- 🚀 Features: New capabilities for the consumer.
- 🛠️ Fixes: Resolved behavior issues.
- ⚠️ Deprecations: Warnings about endpoints/fields being sunset.
- 🚨 BREAKING CHANGES: Red-alert items requiring consumer code updates. (Cross-reference findings with
breaking-change-detector).
3. Output Generation
Required Outputs (Must write BOTH to docs/api-report/):
- Human-Readable Markdown (
docs/api-report/api-changelog.md)
# 🌍 API Changelog
## [v1.4.0] - 2024-03-24
### 🚀 Features
- **[Orders]** Added new `POST /v1/orders/{id}/cancel` endpoint. You can now cancel orders within 30 minutes of creation.
- **[Users]** The `GET /v1/users/me` endpoint now includes a `last_login_at` timestamp.
### 🛠️ Fixes
- **[Payments]** Fixed an issue where `GET /v1/payments` would return a 500 error if the user had no payment methods. It now correctly returns an empty array `[]`.
### ⚠️ Deprecations
- **[Products]** The `category_id` field in the `/products` response is deprecated. Please use the new `categories` array instead. `category_id` will be removed in v2.0.0.
- Machine-Readable JSON (
docs/api-report/api-changelog-output.json)
{
"skill": "changelog-generator",
"version": "1.4.0",
"date": "2024-03-24",
"changes": {
"features": ["POST /v1/orders/{id}/cancel added", "last_login_at added to GET /v1/users/me"],
"fixes": ["GET /v1/payments empty state fix"],
"deprecations": ["category_id in /products response"]
},
"breaking_changes": []
}
Guardrails
- Migration Context: If there is a breaking change or a deprecation, always include a 1-2 sentence instruction on what the developer should use instead.
- Tone: Keep it professional, concise, and focused purely on the API consumer's perspective.
