create-changelog-announcement（创建变更日志公告）

Create Changelog Announcement

This skill guides you through creating complete changelog announcements that include:

1. Detailed changelog documentation page in /docs/blog/entries/
2. Summary entry in /docs/blog/main.mdx
3. Sidebar announcement card in /web/oss/src/components/SidebarBanners/data/changelog.json
4. Roadmap update in /docs/src/data/roadmap.ts
5. GitHub discussion closure (if applicable)
6. Social media announcements (LinkedIn, Twitter, Slack)

Your Core Responsibilities

1. Complete Changelog Creation Workflow

For every changelog announcement, you create THREE coordinated entries:

A. Detailed 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

B. Summary Entry (docs/blog/main.mdx):

• Concise 1-2 paragraph summary
• Version number and date
• Link to detailed entry
• Embedded media if significant feature

C. Sidebar Announcement (web/oss/src/components/SidebarBanners/data/changelog.json):

• One-sentence description
• Link to detailed documentation
• Unique ID with date

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

Sidebar Announcement IDs:

• Format: changelog-YYYY-MM-DD-feature-slug
• Example: changelog-2026-01-09-chat-sessions
• Must be unique to prevent conflicts

Version Format:

• Use semantic versioning: v0.73.0
• Include in summary entry

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:

1. Check if a dedicated feature page exists in /docs/docs/
2. If found, link to it in both the summary and detailed entries
3. 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
• All three entries created (detailed, summary, sidebar)
• Summary links to detailed entry correctly
• 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

Detailed changelog entries:

• Path: /docs/blog/entries/[feature-slug].mdx
• Example: /docs/blog/entries/chat-sessions-observability.mdx

Summary changelog:

• Path: /docs/blog/main.mdx
• Add new entry at the TOP of the file (after imports, before other entries)

Sidebar announcements:

• Path: /web/oss/src/components/SidebarBanners/data/changelog.json
• JSON array, add new entry at the TOP

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. */}

## Overview

[2-3 paragraphs explaining what this feature is and why it matters]

## Key Capabilities

- **Capability 1**: Description
- **Capability 2**: Description
- **Capability 3**: Description

## How It Works

[Step-by-step explanation or code examples]

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]

- [Feature Documentation](https://github.com/docs/path/to/feature)
- [Tutorial](https://github.com/tutorials/path/to/tutorial)

## What's Next

[Optional: What's coming next or related features]

Step 4: Add Summary to main.mdx

Add to /docs/blog/main.mdx at the TOP (after imports):

### [Feature Name](/changelog/feature-slug)

_DD Month YYYY_

**vX.Y.Z**

[1-2 paragraph summary explaining what the feature does and why users should care. Focus on benefits and capabilities.]

[Optional: Add embedded video or image if this is a major feature]

---

Step 5: Add Sidebar Announcement

Add to /web/oss/src/components/SidebarBanners/data/changelog.json:

[
    {
        "id": "changelog-2026-01-09-feature-name",
        "title": "Feature Name (Keep Under 40 Chars)",
        "description": "One-sentence benefit users get from this feature.",
        "link": "https://agenta.ai/docs/changelog/feature-slug"
    },
    // ... existing entries
]

Step 6: Update Roadmap

Update /docs/src/data/roadmap.ts:

If feature was in roadmap:

1. Find the feature in inProgressFeatures array
2. Move it to shippedFeatures array at the top
3. Convert from PlannedFeature format to ShippedFeature format:

- Remove githubUrl field - Add changelogPath field pointing to your detailed entry - Add shippedAt field with ISO date (YYYY-MM-DD)

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:

1. Note the discussion URL from the roadmap entry
2. Check if the discussion should be closed (ask user if unsure)
3. If using gh CLI: gh issue close <number> --repo Agenta-AI/agenta --comment "Shipped in v0.73.0"
4. 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.

1. Run the documentation build:

cd docs && npm run build

1. 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

1. Verify checklist:

• Build completed successfully (npm run build in docs/)
• Read all files to ensure consistency
• Check that links work (relative paths correct)
• Verify JSON syntax in sidebar announcement
• 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:**

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:

- [Track Chat Sessions (Python SDK)](https://github.com/observability/trace-with-python-sdk/track-chat-sessions)
- [Session Tracking (OpenTelemetry)](https://github.com/observability/trace-with-opentelemetry/session-tracking)
- [Observability Overview](https://github.com/observability/overview)

## What's Next

We're continuing to enhance session tracking with upcoming features like session-level annotations, session comparisons, and automated session analysis.

Summary Entry (add to docs/blog/main.mdx):

### [Chat Sessions in Observability](/changelog/chat-sessions-observability)

_9 January 2026_

**v0.73.0**

You can now track multi-turn conversations with chat sessions. All traces with the same session ID are automatically grouped together, letting you analyze complete conversations instead of individual requests.

The new session browser shows key metrics like total cost, latency, and token usage per conversation. Open any session to see all traces with their parent-child relationships. This makes debugging chatbots and AI assistants much easier. Add session tracking with one line of code using either our Python SDK or OpenTelemetry.

---

Sidebar Announcement:

{
    "id": "changelog-2026-01-09-chat-sessions",
    "title": "Chat Sessions in Observability",
    "description": "Track multi-turn conversations with session grouping and cost analytics.",
    "link": "https://agenta.ai/docs/changelog/chat-sessions-observability"
}

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. Detailed entry content for docs/blog/entries/[slug].mdx
2. Summary entry content to add to docs/blog/main.mdx
3. Sidebar announcement JSON to add to changelog.json
4. Confirmation that you checked for related documentation
5. 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 main.mdx and 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: Ensure terminology matches across all three entries

Remember: You're creating user-facing documentation that represents a new feature to thousands of developers. Make it clear, compelling, and easy to understand.