Create Changelog Announcement
This skill guides you through creating complete changelog announcements that include:
- Changelog entry page in
/docs/blog/entries/(the changelog index at/changelogis generated from these automatically, with pagination) - In-app What's New data, regenerated from the entries with
pnpm --filter @agenta/navigation generate:releases - Roadmap update in
/docs/src/data/roadmap.ts - GitHub discussion closure (if applicable)
- Social media announcements (LinkedIn, Twitter, Slack)
Your Core Responsibilities
1. Complete Changelog Creation Workflow
For every changelog announcement, you write one entry and regenerate the in-app data from it:
A. Changelog Entry (docs/blog/entries/[feature-slug].mdx):
-
Comprehensive explanation of the feature or change
-
Code examples, screenshots, or embedded videos
-
Links to related documentation
-
User-focused benefits and use cases
-
Two distinct texts: a short summary for the
/changelogindex, and the full write-up for the entry's own page. The short version is the curated 1-2 paragraph summary (it can differ from the long version's opening; do not just copy the first lines of the long write-up). Structure the file as:---frontmatter--- import Image from "@theme/IdealImage"; {/* only if you use <Image> */} <Summary> {/* Optional hero video or screenshot, shown on the index */} Curated 1-2 paragraph summary shown on the /changelog index. </Summary> {/* truncate */} {/* Repeat the hero video/screenshot here so it also shows on the page */} Full write-up (## sections, videos, code) shown on the entry's page.<Summary>renders only on the index list (as the preview, with a "Read more" link); it renders nothing on the entry page, so the page shows just the full write-up with no duplication. If the feature has a demo video or screenshot, put it inside<Summary>so it appears on the index, and also in the write-up below the marker so it appears on the entry page. Embedded videos and images are capped to a centered 680px in CSS, so use the existing<iframe>/<Image>markup as-is.
B. In-app What's New (web/packages/agenta-navigation/src/releases/changelog.json):
- Generated. Never edit it by hand.
- Run
pnpm --filter @agenta/navigation generate:releasesfromweb/after you add or edit an entry. - The generator groups entries by their version tag into one release, keeps the newest 10
versions, and takes each entry's
<Summary>, its first<Stream src="...">clip, and itsimprovementsandfixeslists. An entry without avX.Y.Ztag is skipped.
2. Information Gathering
Before creating any entry, collect:
- Feature name and description
- Version number (if unclear, ask: "Which version is this changelog entry for?")
- Release date (default to today if not specified)
- Whether user has screenshots/videos (ask if mentioned but not provided)
- Links to related documentation
Never proceed without a clear version identifier and feature description.
3. Writing Style Guidelines
Apply these writing guidelines rigorously:
- Clarity above all else: Use 11th grade English for non-technical terms
- Active voice: "You can now track conversations" not "Conversations can now be tracked"
- Short sentences: Default to punchy sentences; use longer ones only for flow
- Complete sentences: Avoid fragments unless brevity clearly improves readability
- No em dashes (—): Use periods, parentheses (), or semicolons ; instead
- Minimal formatting: Use bold and bullets sparingly—only when they aid scanning
- User-focused: Write "You can now..." not "We've added..."
- Benefits over features: Explain what users can do, not what you built
Examples:
❌ Bad: "We've implemented a new session tracking system that enables users to group related traces—making it easier to analyze conversations."
✅ Good: "You can now group related traces into sessions. This helps you analyze complete conversations and track metrics across multiple turns."
4. ID and Naming Conventions
Changelog Entry File Naming:
- Use kebab-case with descriptive names
- Examples:
chat-sessions-observability.mdx,pdf-support-in-playground.mdx - Keep under 60 characters
Version Format:
- Use semantic versioning:
v0.73.0 - Include it as the entry's tag (
tags: [v0.73.0]); the changelog index shows it as a version chip next to the date - All entries with the same tag form one release in the app's What's New dialog
4a. Improvements and Fixes
Smaller changes in a release go in the entry's frontmatter, not in their own entry. Both
lists are optional. Each item has an area (the product area, for example Chat, Files,
Settings) and a text:
improvements:
- area: Chat
text: "Long replies render faster."
fixes:
- area: Settings
text: "Saving a provider key no longer clears the model list."
- One line per item. Write what the user notices, not what the code changed.
- Quote
textwhen it contains a colon. - The docs entry page and the What's New dialog show these lists under the content as "Improvements" and "Fixes".
- Use only these keys and this shape. The generator fails on anything else.
5. Media Handling
When user mentions videos or screenshots:
For YouTube videos (in detailed entry):
<div style={{display: 'flex', justifyContent: 'center', marginTop: "20px", marginBottom: "20px", flexDirection: 'column', alignItems: 'center'}}>
<iframe
width="100%"
height="500"
src="https://www.youtube.com/embed/VIDEO_ID"
title="Feature Demo"
frameBorder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
allowFullScreen
></iframe>
</div>
For images (in detailed entry):
<Image
img={require('/static/images/changelog/feature-name.png')}
alt="Feature description"
style={{display: 'block', margin: '20px auto', textAlign: 'center'}}
/>
Ask for specifics if unclear:
- "Do you have the YouTube URL for the demo video?"
- "How many screenshots should I add placeholders for?"
- "Where should I place the images in the narrative?"
6. Feature Documentation Integration
Always search for related documentation:
- Check if a dedicated feature page exists in
/docs/docs/ - If found, link to it in both the summary and detailed entries
- If not found, note this and ask: "Should we create documentation for this feature?"
Documentation links format:
- Use relative paths:
/observability/trace-with-python-sdk/track-chat-sessions - Not absolute URLs unless external
7. Quality Assurance Checklist
Before finalizing, verify:
- Version number present and correct
- Entry created, with
improvements/fixesfrontmatter if the release has them -
pnpm --filter @agenta/navigation generate:releasesrun andchangelog.jsonupdated - Curated summary wrapped in
<Summary>, then{/* truncate */}, then the full write-up - Active voice used where possible
- No em dashes present
- Feature documentation linked if applicable
- Media placeholders added if mentioned
- Writing style guidelines followed
- IDs and file names follow conventions
- All required frontmatter included
8. File Locations Reference
Changelog entries:
- Path:
/docs/blog/entries/[feature-slug].mdx - Example:
/docs/blog/entries/chat-sessions-observability.mdx - The changelog index page at
/changelogis built automatically from these files (sorted bydate, paginated). There is no separate summary file to maintain.
In-app What's New data:
- Path:
/web/packages/agenta-navigation/src/releases/changelog.json(generated) - Generator:
/web/packages/agenta-navigation/scripts/build-releases.mjs
Step-by-Step Workflow
Step 1: Gather Information
Ask the user for any missing information:
- What version is this for?
- Do you have a demo video or screenshots?
- What's the primary benefit users will get from this?
- Are there existing docs for this feature I should link to?
Step 2: Search for Related Documentation
# Search for related docs
grep -r "session" docs/docs/observability --include="*.mdx" --include="*.md"
Step 3: Create Detailed Entry
Create /docs/blog/entries/[feature-slug].mdx:
IMPORTANT: Use correct frontmatter format (no authors field):
---
title: "Feature Name"
slug: feature-name-slug
date: YYYY-MM-DD
tags: [vX.Y.Z]
description: "One-sentence description of the feature."
---
{/* NOTE: Do NOT add an H1 heading here. The frontmatter title is automatically rendered as H1 by Docusaurus. */}
<Summary>
[Curated 1-2 paragraph summary. This is the SHORT version shown on the
/changelog index. It can differ from the long write-up's opening.]
</Summary>
{/* truncate */}
## Key Capabilities
- **Capability 1**: Description
- **Capability 2**: Description
- **Capability 3**: Description
## How It Works
[Step-by-step explanation or code examples]
```python
# Code example if applicable
import agenta as ag
ag.tracing.store_session(session_id="conversation_123")
Use Cases
[Real-world scenarios where this feature helps]
Getting Started
[Links to documentation, tutorials, or guides]
What's Next
[Optional: What's coming next or related features]
### Step 4: Write the Summary and Place the Truncate Marker
The `/changelog` index shows the `<Summary>` block (with a "Read more" link);
the entry page shows everything below `{/* truncate */}`. So:
- Put the curated short summary inside `<Summary>...</Summary>`, then the
`{/* truncate */}` marker, then the full write-up.
- Leave blank lines inside the `<Summary>` tags so the content parses as
Markdown (links and bold work).
- If there is a demo video or screenshot, include it inside `<Summary>` (so it
shows on the index) and again in the write-up below the marker (so it shows
on the entry page).
- Every entry needs content below the marker (the full write-up); that is what
the entry page renders.
### Step 5: Regenerate the In-App What's New Data
From `web/`:
```bash
pnpm --filter @agenta/navigation generate:releases
Check that the printed version list contains your version and the feature count you expect.
Commit the updated changelog.json with the entry.
Step 6: Update Roadmap
Update /docs/src/data/roadmap.ts:
If feature was in roadmap:
- Find the feature in
inProgressFeaturesarray - Move it to
shippedFeaturesarray at the top - Convert from
PlannedFeatureformat toShippedFeatureformat:- Remove
githubUrlfield - Add
changelogPathfield pointing to your detailed entry - Add
shippedAtfield with ISO date (YYYY-MM-DD)
- Remove
Example:
// Move from inProgressFeatures to top of shippedFeatures:
{
id: "chat-session-view",
title: "Chat Sessions in Observability",
description: "Track multi-turn conversations with session grouping...",
changelogPath: "/docs/changelog/chat-sessions-observability",
shippedAt: "2026-01-09",
labels: [{name: "Observability", color: "DE74FF"}],
}
Step 7: Check GitHub Discussion
If the roadmap item had a githubUrl pointing to a GitHub discussion:
- Note the discussion URL from the roadmap entry
- Check if the discussion should be closed (ask user if unsure)
- If using
ghCLI:gh issue close <number> --repo Agenta-AI/agenta --comment "Shipped in v0.73.0" - If CLI not available, note the discussion URL for manual closure
Step 8: Create Social Media Announcements
Follow the guidelines in: .claude/skills/write-social-announcement/SKILL.md
That skill contains comprehensive guidelines for writing authentic announcements that avoid common AI writing patterns. Key points:
- Vary your openings (don't always start with "We just shipped")
- Avoid AI vocabulary: "crucial", "pivotal", "showcases", "underscores", "landscape", "tapestry"
- No superficial "-ing" analyses at end of sentences
- No rhetorical questions ("Working with large test sets?")
- No cliché closings ("Small changes, but they add up")
- Be specific and direct
Create SOCIAL_ANNOUNCEMENTS.md with sections for LinkedIn, Twitter, and Slack
Step 9: Build and Verify
CRITICAL: Always run the build to verify no errors before finishing.
- Run the documentation build:
cd docs && npm run build
-
If build fails, fix errors immediately:
- Common error: Missing authors field - Remove
authors: [agenta]from frontmatter - Correct frontmatter format (example from existing entries):
--- title: "Feature Name" slug: feature-name-slug date: YYYY-MM-DD tags: [vX.Y.Z] description: "Brief description" --- - Invalid MDX syntax - Check for unclosed tags, incorrect JSX
- Broken links - Verify all relative paths exist
- Common error: Missing authors field - Remove
-
Verify checklist:
- Build completed successfully (
npm run buildin docs/) - Read all files to ensure consistency
- Check that links work (relative paths correct)
- Generator ran without errors and lists the new version
- Ensure version numbers match across files
- Confirm writing style follows guidelines
- Roadmap updated correctly
- Social announcements created
Common Patterns and Examples
Example 1: New Feature Announcement (Chat Sessions)
Detailed Entry (docs/blog/entries/chat-sessions-observability.mdx):
---
title: "Chat Sessions in Observability"
slug: chat-sessions-observability
date: 2026-01-09
tags: [v0.73.0]
description: "Track and analyze multi-turn conversations with session grouping, cost analytics, and conversation flow visualization."
---
{/* NOTE: Do NOT add an H1 heading here. The frontmatter title is automatically rendered as H1 by Docusaurus. */}
## Overview
Chat sessions bring conversation-level observability to Agenta. You can now group related traces from multi-turn conversations together, making it easy to analyze complete user interactions rather than individual requests.
This feature is essential for debugging chatbots, AI assistants, and any application with multi-turn conversations. You get visibility into the entire conversation flow, including costs, latency, and intermediate steps.
## Key Capabilities
- **Automatic Grouping**: All traces with the same `ag.session.id` attribute are automatically grouped together
- **Session Analytics**: Track total cost, latency, and token usage per conversation
- **Session Browser**: Dedicated UI showing all sessions with first input, last output, and key metrics
- **Session Drawer**: Detailed view of all traces within a session with parent-child relationships
- **Real-time Monitoring**: Auto-refresh mode for monitoring active conversations
## How It Works
Add a session ID to your traces using either the Python SDK or OpenTelemetry:
**Python SDK:**
```python
import agenta as ag
ag.tracing.store_session(session_id="conversation_123")
OpenTelemetry:
span.setAttribute('ag.session.id', 'conversation_123')
The UI automatically detects session IDs and groups traces together. You can use any format for session IDs: UUIDs, composite IDs (user_123_session_456), or custom formats.
Use Cases
- Debug Chatbots: See the complete conversation flow when users report issues
- Monitor Multi-turn Agents: Track how your agent handles follow-up questions and context
- Analyze Conversation Costs: Understand which conversations are expensive and why
- Optimize Performance: Identify latency issues across entire conversations, not just single requests
Getting Started
Learn more in our documentation:
What's Next
We're continuing to enhance session tracking with upcoming features like session-level annotations, session comparisons, and automated session analysis.
### Example 2: Integration Announcement
**For integrations, focus on:**
- What you can now integrate with
- How easy it is to set up (mention "one line of code" if true)
- Key benefits specific to that integration
- Link to integration docs
### Example 3: Improvement Announcement
**For improvements, emphasize:**
- Quantifiable improvements (e.g., "10x faster", "50% reduction")
- Before/after comparison if dramatic
- How this helps users (time saved, better experience)
## Decision-Making Framework
**When Information is Missing:**
- Version number unclear → Ask immediately before proceeding
- Feature scope ambiguous → Request clarification and examples
- Media availability uncertain → Confirm with user before adding placeholders
- Categorization unclear → Ask whether it's a new feature, improvement, or bug fix
**When Editing Existing Entries:**
- Always preserve factual accuracy and original intent
- Improve clarity and style without changing meaning
- Flag technical inaccuracies to the user rather than guessing
## Output Format
When creating a changelog announcement, provide:
1. **Entry content** for `docs/blog/entries/[slug].mdx` (curated summary in `<Summary>`, then `{/* truncate */}`, then the full write-up)
2. **Generator output** (the version list `generate:releases` printed)
3. **Confirmation** that you checked for related documentation
4. **Any questions** or clarifications needed
**Be proactive** in identifying unclear requirements. Ask specific questions rather than making assumptions. Your goal is to produce changelog entries that are immediately publishable without requiring revision.
## Tips for Success
1. **Read existing entries first**: Before creating new entries, read 2-3 recent entries in `entries/` to match the tone and structure
2. **Be concise**: Users skim changelogs. Front-load the benefit in every sentence.
3. **Link generously**: Help users find more information easily
4. **Test your work**: Read the entries out loud to catch awkward phrasing
5. **Consistency matters**: Use the same area names across releases (`Chat`, not `Chats` one week and `Chat` the next)
---
**Remember**: You're creating user-facing documentation that represents a new feature to thousands of developers. Make it clear, compelling, and easy to understand.