changelog-writer

Create user-focused, SEO-optimized changelog entries for software releases. Use when writing release notes, version updates, product changelogs, or "what's new" documentation for developer tools.

⭐13stars🔀2forks📁View on GitHub🕐Updated Dec 24, 2025⬇️2downloads

When & Why to Use This Skill

The Changelog Writer skill streamlines the creation of professional, user-centric, and SEO-optimized release notes for software products. By cross-referencing technical implementation documents, it ensures factual accuracy while maintaining a concise, benefit-driven tone that bridges the gap between technical updates and user value. It also incorporates AEO (AI Engine Optimization) best practices to ensure product updates are easily discoverable by both human users and AI citation engines.

Use Cases

  • Automating the generation of 'What's New' documentation for developer tools based on pull requests and internal implementation status.
  • Creating SEO-friendly version update announcements to improve organic search visibility for specific product features and technical keywords.
  • Drafting AI-ready (AEO) summaries and excerpts to ensure product updates are accurately indexed and cited by AI search engines and LLMs.
  • Standardizing changelog formats across engineering teams to ensure consistent branding, professional tone, and technical precision in release communications.
namechangelog-writer
descriptionCreate user-focused, SEO-optimized changelog entries for software releases. Use when writing release notes, version updates, product changelogs, or "what's new" documentation for developer tools.
allowed-toolsRead, Grep, Glob, Write, Edit

Changelog Writer

Create clear, accurate changelog entries that help developers understand what's new in Lightfast releases.

Critical: Fact-Check First

Before writing anything, verify against docs/architecture/implementation-status/README.md:

  1. Check implementation status to verify:

    • What's actually completed vs planned
    • Current limitations and known gaps
    • Technical accuracy of claims
  2. Never oversell:

    • Use specific names: "GitHub File Sync (File Contents)" not "GitHub Integration"
    • Disclose limitations: "Currently supports X; Y coming in vZ"
    • Be honest about conditionals: "when 3+ customers request"
  3. Verify every claim:

    • If you cite a number, confirm it's in implementation docs
    • If you mention a feature, confirm it exists in production
    • When uncertain, ask for clarification

Writing Guidelines

  1. Concise & scannable: 1-3 sentences per feature (Cursor-style brevity)
  2. Lead with benefit: Start with what users can do, then how
  3. Be transparent: Mention beta status, rollout timelines, limitations
  4. User-focused but technical: Balance benefits with specifics developers need
  5. Active voice: "You can now..." not "Users are able to..."
  6. No emoji: Professional tone
  7. Specific examples: Include config snippets, API calls
  8. SEO-conscious: Use target keywords naturally
  9. AEO-conscious: Write tldr for AI citation engines, excerpt for listings
  10. FAQ quality: Questions must match real search queries, answers must be complete

Workflow

  1. Gather input: PR numbers, URLs, or manual change list
  2. Read implementation status for fact-checking
  3. Draft following templates
  4. Cross-check claims against implementation reality
  5. Add SEO elements per seo-requirements
  6. Review with checklist

Quick Reference

Do

  • "GitHub File Sync (File Contents)" with limitations disclosed
  • "When 3+ customers request: Linear integration"
  • Include code examples for every major feature
  • Link to 3-5 related docs

Don't

  • "GitHub Integration" (vague - what does it cover?)
  • "Coming soon: Linear, Notion, Slack!" (when at 0%)
  • Long paragraphs (keep to 1-3 sentences per feature)
  • Claims without verification

Output

Save drafts to: thoughts/changelog/{title-slug}-{YYYYMMDD-HHMMSS}.md

Required Frontmatter Fields

Every draft MUST include:

  • title, slug, publishedAt (core)
  • excerpt, tldr (AEO)
  • seo.metaDescription, seo.focusKeyword (SEO)
  • _internal.status, _internal.source_prs (traceability)

Slug Format

Always use: 0-<version>-lightfast-<feature-slug>

Examples:

  • 0-1-lightfast-github-file-sync-semantic-search
  • 0-2-lightfast-pr-metadata-linear-integration

Recommended:

  • seo.secondaryKeyword, seo.faq[] (enhanced SEO)

The frontmatter structure maps directly to ChangelogEntryInput type. Use /publish_changelog to publish drafts to BaseHub.

See resources/templates.md for complete frontmatter template.

Resources