AGENT SKILL

ams-changelog-pro

暂无简介

License 许可
MIT
所属仓库
TanNhatCMS/jarvis
最近更新
2026-11-07
Stars
★ 0
Forks
1

03 SKILL.md 正文

Changelog Pro

Overview

A changelog is the human-readable story of what changed and why it matters — distinct from git history (for developers) and marketing (for prospects). Done well, it builds trust: users can see what's new, what's fixed, and what might break them. This skill covers the Keep-a-Changelog discipline, writing entries users care about, and automating generation without producing robotic noise.

The through-line: changelogs are for humans — write what changed from the user's perspective, in language they'll understand.

When to use

  • Writing changelog entries for a release.
  • Setting up changelog conventions (Keep-a-Changelog, changesets).
  • Automating release notes from commits or PRs.
  • Reviewing changelogs for clarity and completeness.
  • Deciding what belongs in a changelog vs git history.

Core concepts

  • Keep-a-Changelog format. CHANGELOG.md with ## [Unreleased] at top, version sections with dates, and categorized entries: Added / Changed / Deprecated / Removed / Fixed / Security. Reverse-chronological, one file, human-written summaries — the de facto standard for a reason.
  • User perspective, always. "Fixed: checkout no longer double-charges on retry" — not "refactored payment idempotency layer." Users care about behavior change, not implementation. Write the impact, link the detail (PR/issue) for the curious.
  • Breaking changes, loudly. A dedicated, unmissable section at the top of the release: what breaks, who it affects, and exactly how to migrate (before/after code). Breaking changes buried in "Changed" erode trust permanently.
  • The Unreleased section. Every PR that changes behavior adds an entry under ## [Unreleased] in the same PR. Release time = rename the section + date. No archaeology, no forgotten entries.
  • Automation with judgment. Generate drafts from conventional commits or PR titles, but curate before publishing — raw commit logs are noise ("fix typo", "wip"). Changesets (per-PR change descriptions) produce the best automated changelogs because humans write the entries at change time.
  • Version links and dates. [1.2.0] - 2026-09-26 with link definitions to diffs/tags at the bottom. Dates matter (users correlate with their issues); diff links serve the deeply curious.

Practical workflow

  1. Adopt the format. CHANGELOG.md at repo root, Keep-a-Changelog structure, ## [Unreleased] section live from day one. Add "changelog entry" to the PR template checklist.
  2. Write entries per PR. In the same PR as the change: one bullet under Unreleased, categorized, user-perspective language, PR/issue link. Small habit, huge payoff.
  3. Curate at release. Read the Unreleased section as a user: reorder by importance, merge related bullets, elevate breaking changes to the top with migration guides, cut internal noise.
  4. Publish consistently. Changelog updated in the release commit; release notes (GitHub releases) mirror or link it; announce breaking changes through every channel users watch.
  5. Automate the draft. Conventional commits → generated draft, or changesets → compiled notes; human curates. Never ship raw generated logs as the changelog.
  6. Maintain the discipline. Review changelog entries in PR review like code; reject "various fixes" entries; keep the format consistent across releases.

Example entries:

## [Unreleased]

## [2.4.0] - 2026-09-26

### ⚠️ Breaking changes
- **API:** `POST /orders` now requires `idempotency_key` (was optional).
  Migration: generate a UUID per order attempt client-side; see #1234.
  Affects: all API consumers creating orders.

### Added
- Checkout now supports saved payment methods (#1230)
- Webhook event `refund.processed` for refund status tracking (#1228)

### Fixed
- Double charges when "Place order" was tapped twice quickly (#1224)
- Order list pagination skipping items when new orders arrived (#1219)

### Security
- Rate limiting added to password-reset endpoint (abuse prevention) (#1221)

Common pitfalls

  • Git log as changelog. Dumping commit messages ("fix stuff", "wip", "address review feedback") — noise that teaches users to never read it. Curate for humans.
  • Developer perspective. "Refactored auth middleware" means nothing to users. Translate to impact: "Sign-in is now 40% faster" or omit if truly internal.
  • Missing breaking changes. Or burying them. Breaking changes are the highest-value changelog content — prominent, with migration paths. Users plan upgrades around them.
  • Stale or missing Unreleased. Entries written at release time from memory — incomplete and wrong. Per-PR entries under Unreleased, enforced by checklist/review.
  • "Various bug fixes." The entry that says nothing. Each fix gets its specific bullet, or the changelog isn't doing its job.
  • No dates or versions. Undated sections, missing version links — users can't correlate releases with their experience. Date every release; link every version.
  • Changelog vs release notes confusion. The changelog is the durable record (in the repo); release notes are the announcement (can link it). Keep the changelog canonical; don't maintain two divergent sources.

04 同仓库更多 Skills

TanNhatCMS
TanNhatCMS/jarvis

web-scrape

Turn web pages into LLM-ready markdown via the Firecrawl API (renders JS, anti-bot handling). Use when browser_open/fetch fails on JS-heavy pages, or when you need clean markdown/structured extraction from a site. Requires FIRECRAWL_API_KEY.

★ 0
TanNhatCMS
TanNhatCMS/jarvis

design-taste-frontend

tasteskill v2, the anti-slop frontend skill. Art direction for websites, distilled from a study of 247 curated gallery sites (One Page Love, Awwwards Sites of the Day). Deals researched directions (idea, composition, type, palette, photographs, section blueprints) from a library, enforces a strict no-slop house style with a real-browser inspector, and runs a look-and-fix loop on screenshots. Use this whenever you build, design, redesign, restyle, polish or review a landing page, marketing site, portfolio, product page, one-pager, hero or any public-facing web page, in any stack (HTML/CSS, React, Next.js, Vue, Svelte, Astro, Tailwind) — also when the user says a page looks generic, templated, "AI-made", sloppy, or asks to make it look designed, premium, award-level or less like every other site. Not for dashboards or app screens.

★ 0
TanNhatCMS
TanNhatCMS/jarvis

test-driven-development

Use when implementing any feature or bugfix, before writing implementation code

★ 0
TanNhatCMS
TanNhatCMS/jarvis

systematic-debugging

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

★ 0
TanNhatCMS
TanNhatCMS/jarvis

requesting-code-review

Use when completing tasks, implementing major features, or before merging to verify work meets requirements

★ 0
TanNhatCMS
TanNhatCMS/jarvis

brainstorming

You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).

★ 0