| name | media-insertion |
| description | Insert images and videos from Slack messages into changelog markdown. Use when you have media files downloaded from Slack that need to be included in documentation. |
| targets | ["*"] |
Media Insertion for Changelogs
This skill teaches you how to properly insert media (images and videos) from Slack into changelog content.
Overview
When Slack messages include media files, the fetch_messages_from_channel tool downloads them to:
./docs/updates/media/YYYY-MM-DD/filename
You must insert references to these files in the markdown content so they appear in the final changelog.
Step 1: Identify Media from Slack Response
The Slack tool response includes processed_files for each message with media:
📝 Message 1:
💬 Text: Check out this new feature!
📎 Files (1):
🖼️ Image: feature-screenshot_abc123.png
Path: ./docs/updates/media/2025-11-06/feature-screenshot_abc123.png
Step 2: Insert Media References in Markdown
When writing the changelog content, insert the image reference right after describing the feature:
### New feature name
Description of the feature and what it does.
More details about the feature...
Important:
- Use the local path format:
./media/YYYY-MM-DD/filename
- Write descriptive alt text that explains what the image shows (be specific, not generic)
- Place images where they make sense contextually (after introducing the feature)
- Only reference images that actually exist in the Slack response - check the file paths shown
- For videos (.mp4, .mov, .webm), use the same markdown syntax
Step 3: Verify Images Before Inserting
Before adding an image reference to your markdown:
- Check the Slack tool response for the exact filename
- Verify the path matches:
./docs/updates/media/YYYY-MM-DD/filename
- Use that exact filename in your markdown reference:
./media/YYYY-MM-DD/filename
DO NOT insert image references for files that weren't downloaded or don't appear in the Slack response.
Step 4: Template Formatter Converts to Final Format
The template_formatter agent will later:
- Verify each image file exists at
./docs/updates/media/YYYY-MM-DD/filename
- Convert paths:
./media/YYYY-MM-DD/filename → /images/changelog/YYYY-MM-DD/filename
- Wrap in Frame tags:
<Frame><img src="/images/changelog/..." alt="..." /></Frame>
- Convert video references to:
<Frame><video src="/images/changelog/..." controls /></Frame>
Examples
Example 1: Single Image with Feature
Slack message:
- Text: "New planning mode UI with task list"
- Image:
planning-mode_xyz789.png
Changelog content you write:
### Agent planning mode improvements
Agent now shows a clear task list in planning mode, making it easier to review and approve what will be built.
This improvement addresses feedback from users who wanted more visibility...
Example 2: Multiple Images for One Feature
Slack message:
- Text: "Redesigned settings page"
- Images:
settings-before_abc123.png, settings-after_def456.png
Changelog content you write:
### Settings page redesign
We've redesigned the settings page with a cleaner layout and better organization.
The new design groups related settings together and uses clearer labels:
Example 3: Video Demo
Slack message:
- Text: "Agent can now stream responses"
- Video:
streaming-demo_ghi789.mp4
Changelog content you write:
### Real-time Agent streaming
Agent responses now stream in real-time, showing you progress as it works.
This makes the experience feel faster and more interactive.
Best Practices
- Always include media when available - If Slack downloaded a file, it's relevant to the update
- Write descriptive alt text - Explain what the image shows, not just "screenshot"
- Place strategically - Insert images after you introduce the concept they illustrate
- Use local paths - Don't try to convert paths yourself, use
./media/YYYY-MM-DD/filename
- One image per feature minimum - Visual updates should have visual proof
Common Mistakes to Avoid
❌ Don't skip images:
### New dashboard
We redesigned the dashboard.
✅ Do include them:
### New dashboard
We redesigned the dashboard with a modern layout.
❌ Don't use placeholder text:
✅ Do write descriptive alt text:
Quick Checklist
Before finishing your changelog content:
