From 129a21d6d46f4de00977e9fbd9cdb1450f52c6e0 Mon Sep 17 00:00:00 2001
From: Kieran Klaassen <kieranklaassen@gmail.com>
Date: Sat, 29 Nov 2025 13:06:50 -0800
Subject: [PATCH] [2.8.3] Fix gemini-imagegen file format documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add critical documentation about Gemini returning JPEG by default
- Explain that using .jpg extension avoids "Image does not match media type" errors
- Provide PNG conversion example when needed
- Include format verification command

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../.claude-plugin/plugin.json                |  2 +-
 plugins/compounding-engineering/CHANGELOG.md  |  6 +++
 .../skills/gemini-imagegen/SKILL.md           | 37 +++++++++++++++++++
 3 files changed, 44 insertions(+), 1 deletion(-)

diff --git a/plugins/compounding-engineering/.claude-plugin/plugin.json b/plugins/compounding-engineering/.claude-plugin/plugin.json
index 451e070..316cbf3 100644
--- a/plugins/compounding-engineering/.claude-plugin/plugin.json
+++ b/plugins/compounding-engineering/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "compounding-engineering",
-  "version": "2.8.2",
+  "version": "2.8.3",
   "description": "AI-powered development tools. 24 agents, 16 commands, 11 skills, 2 MCP servers for code review, research, design, and workflow automation.",
   "author": {
     "name": "Kieran Klaassen",
diff --git a/plugins/compounding-engineering/CHANGELOG.md b/plugins/compounding-engineering/CHANGELOG.md
index 2701c42..07f3558 100644
--- a/plugins/compounding-engineering/CHANGELOG.md
+++ b/plugins/compounding-engineering/CHANGELOG.md
@@ -5,6 +5,12 @@ All notable changes to the compounding-engineering plugin will be documented in
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.8.3] - 2025-11-29
+
+### Fixed
+
+- **`gemini-imagegen` skill** - Added critical documentation about file format handling. Gemini returns JPEG by default, so using `.jpg` extension is required to avoid "Image does not match media type" API errors. Added examples for PNG conversion when needed and format verification.
+
 ## [2.8.2] - 2025-11-28
 
 ### Changed
diff --git a/plugins/compounding-engineering/skills/gemini-imagegen/SKILL.md b/plugins/compounding-engineering/skills/gemini-imagegen/SKILL.md
index 7c0d6e9..c8c6d74 100644
--- a/plugins/compounding-engineering/skills/gemini-imagegen/SKILL.md
+++ b/plugins/compounding-engineering/skills/gemini-imagegen/SKILL.md
@@ -192,9 +192,46 @@ response = client.models.generate_content(
 )
 ```
 
+## Important: File Format & Media Type
+
+**CRITICAL:** The Gemini API returns images in JPEG format by default. When saving, always use `.jpg` extension to avoid media type mismatches.
+
+```python
+# CORRECT - Use .jpg extension (Gemini returns JPEG)
+image.save("output.jpg")
+
+# WRONG - Will cause "Image does not match media type" errors
+image.save("output.png")  # Creates JPEG with PNG extension!
+```
+
+### Converting to PNG (if needed)
+
+If you specifically need PNG format:
+
+```python
+from PIL import Image
+
+# Generate with Gemini
+for part in response.parts:
+    if part.inline_data:
+        img = part.as_image()
+        # Convert to PNG by saving with explicit format
+        img.save("output.png", format="PNG")
+```
+
+### Verifying Image Format
+
+Check actual format vs extension with the `file` command:
+
+```bash
+file image.png
+# If output shows "JPEG image data" - rename to .jpg!
+```
+
 ## Notes
 
 - All generated images include SynthID watermarks
+- Gemini returns **JPEG format by default** - always use `.jpg` extension
 - Image-only mode (`responseModalities: ["IMAGE"]`) won't work with Google Search grounding
 - For editing, describe changes conversationally—the model understands semantic masking
 - Default to 1K resolution for speed; use 2K/4K when quality is critical