feat: Mandatory JPG generation with SVG provider

SVG generation now ALWAYS produces both .svg and .jpg files.
GitHub requires a raster image (JPG/PNG) for social preview settings,
so the JPG is mandatory for actual use.

- SVG: editable source file (10-50KB)
- JPG: for GitHub upload (1280x640, quality 90, <1MB)

Updated:
- SKILL.md with mandatory conversion step
- commands/social-preview.md with dual output
- commands/all.md with JPG in summary
- config-svg.md example with expected outputs
- CHANGELOG.md with new feature

Author: zircote

CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **[social-preview]**: Mandatory JPG generation with SVG provider
+  - SVG generation now ALWAYS produces both `.svg` and `.jpg` files
+  - JPG is required for GitHub social preview (GitHub doesn't accept SVG)
+  - JPG specs: 1280x640, quality 90, < 1MB
+  - Both files uploaded when using `--upload` flag
+
 ### Fixed
 
 - **[setup]**: Updated setup wizard with SVG-first provider options

commands/all.md

@@ -71,15 +71,17 @@ Generate social preview based on provider:
 
 **SVG (default)**:
 - Generate clean SVG using domain templates
-- Save to `.github/social-preview.svg`
-- If `--dark-mode`, generate dark variant
+- Save SVG to `.github/social-preview.svg`
+- **MANDATORY: Convert to JPG** (`.github/social-preview.jpg`)
+  - Dimensions: 1280x640, Quality: 90, Size: < 1MB
+- If `--dark-mode`, generate dark variants (SVG + JPG)
 
 **DALL-E 3 / Gemini**:
 - Generate optimized image prompt
 - Call API and save PNG
 - Save to `.github/social-preview.png`
 
-Output the generated file location (or prompt if manual).
+Output the generated file locations (SVG + JPG for SVG provider, or prompt if manual).
 
 #### Step 4c: README Enhancement
 
@@ -104,8 +106,9 @@ Display complete summary:
 
 ### Social Preview
 - Provider: svg (default)
-- Output: .github/social-preview.svg
-- Size: X KB
+- SVG Output: .github/social-preview.svg (X KB)
+- JPG Output: .github/social-preview.jpg (X KB) - **For GitHub upload**
+- Dimensions: 1280x640
 - [Generated/Pending]
 
 ### README Enhancement
@@ -145,10 +148,12 @@ If `--apply` flag or user confirms:
 
 | Provider | Social Preview | Infographic | Cost | Speed |
 |----------|---------------|-------------|------|-------|
-| **svg** (default) | SVG file | SVG file | Free | Instant |
+| **svg** (default) | SVG + JPG | SVG file | Free | Instant |
 | **dalle-3** | PNG image | PNG image | ~$0.16 | 10-30s |
 | **gemini** | PNG image | PNG image | ~$0.08 | 6-20s |
 
+**Note**: SVG provider always generates both `.svg` (editable) and `.jpg` (for GitHub upload).
+
 ## Example Usage
 
 ```bash
@@ -179,9 +184,10 @@ If `--apply` flag or user confirms:
 
 - Run without `--apply` first to review changes
 - SVG generation is free and instant (recommended default)
+- SVG always generates JPG for GitHub compatibility
 - Ensure `gh` CLI is authenticated for metadata updates
 - Configure `.claude/github-social.local.md` for custom settings
-- Social preview requires manual GitHub settings update after upload
+- Social preview requires selecting the **JPG** in GitHub settings
 - Use `--dark-mode` for repositories viewed in both themes
 
 ## Related Commands

commands/social-preview.md

@@ -17,7 +17,11 @@ The image must meet GitHub's social preview requirements:
 - Minimum: 640x320 pixels
 - Recommended: 1280x640 pixels (2:1 aspect ratio)
 - Maximum file size: 1MB
-- Output location: `.github/social-preview.svg` (default) or `.github/social-preview.png`
+- Output locations:
+  - `.github/social-preview.svg` - Editable source file
+  - `.github/social-preview.jpg` - **Always generated** (required for GitHub upload)
+
+**IMPORTANT**: GitHub requires a raster image (JPG/PNG) for social preview. SVG generation ALWAYS produces both SVG and JPG files.
 
 ## Process
 
@@ -58,8 +62,12 @@ Use the social-preview skill based on provider setting:
 1. Design visual concept based on project domain
 2. Generate clean SVG following domain templates
 3. Apply svg_style (minimal, geometric, illustrated)
-4. Save to output path (`.github/social-preview.svg`)
-5. If `dark_mode: both`, generate dark variant as well
+4. Save SVG to output path (`.github/social-preview.svg`)
+5. **MANDATORY: Convert SVG to JPG** (`.github/social-preview.jpg`)
+   - Dimensions: 1280x640
+   - Quality: 90
+   - File size: < 1MB
+6. If `dark_mode: both`, generate dark variants (SVG and JPG)
 
 **For DALL-E 3** (`--provider=dalle-3`):
 1. Verify `OPENAI_API_KEY` is available
@@ -88,12 +96,13 @@ If upload is requested:
 
 ### 5. Report Results
 
-**If SVG generated**:
-- Confirm file location and size
-- Display the SVG content (or path)
-- If `dark_mode: both`, report both variants
+**If SVG generated** (always includes JPG):
+- Confirm SVG file location and size
+- **Confirm JPG file location and size** (for GitHub upload)
+- Report dimensions (1280x640)
+- If `dark_mode: both`, report all variants (SVG + JPG for each)
 
-**If image generated (PNG)**:
+**If AI-generated image (DALL-E/Gemini)**:
 - Confirm file location
 - Report dimensions and file size
 - If uploaded: provide commit URL
@@ -107,11 +116,13 @@ If upload is requested:
 
 | Provider | Output | Cost | Speed | Quality |
 |----------|--------|------|-------|---------|
-| **svg** (default) | SVG file | Free | Instant | Clean, predictable |
+| **svg** (default) | SVG + JPG | Free | Instant | Clean, predictable |
 | **dalle-3** | PNG image | ~$0.08 | 5-15s | Artistic, varied |
 | **gemini** | PNG image | ~$0.039 | 3-10s | Good quality |
 | **manual** | Text prompt | Free | Instant | N/A |
 
+**Note**: SVG provider always generates both `.svg` (editable source) and `.jpg` (for GitHub upload).
+
 ## Example Usage
 
 ```bash
@@ -140,13 +151,15 @@ If upload is requested:
 ## GitHub Upload Instructions
 
 If `--upload` was used:
-- The image has been committed to the repository
-- Direct user to repository Settings → General → Social preview to select the uploaded image
+- Both SVG and JPG have been committed to the repository
+- Direct user to repository Settings → General → Social preview to select the **JPG** image
 
 If manual upload needed:
 1. Go to repository Settings
 2. Under "Social preview", click "Edit"
-3. Upload the generated image
+3. Upload the **JPG** file (`.github/social-preview.jpg`)
 4. Save changes
 
+**Important**: GitHub requires a raster image (JPG/PNG) for social preview. Upload the `.jpg` file, not the `.svg`.
+
 The image will appear when the repository is shared on social media platforms.

skills/social-preview/SKILL.md

@@ -20,8 +20,12 @@ All generated images must meet GitHub's social preview requirements:
 - **Minimum**: 640x320 pixels
 - **Recommended**: 1280x640 pixels (2:1 aspect ratio)
 - **Maximum file size**: 1MB
-- **Formats**: SVG (default), PNG, JPG, GIF
-- **Default output**: `.github/social-preview.svg`
+- **Formats**: JPG (required for GitHub), SVG (source file)
+- **Default outputs**:
+  - `.github/social-preview.svg` - Editable source file
+  - `.github/social-preview.jpg` - **Always generated** for GitHub upload
+
+**IMPORTANT**: GitHub's social preview setting requires a raster image (JPG/PNG). SVG generation MUST ALWAYS also produce a JPG file.
 
 ## Workflow
 
@@ -180,10 +184,22 @@ If `dark_mode: true` or `dark_mode: both`:
 - Adjust accent colors for dark backgrounds
 - If `both`: save as `[name].svg` and `[name]-dark.svg`
 
-**Save SVG**:
+**Save SVG and Convert to JPG**:
 1. Write SVG content to `output_path` (default: `.github/social-preview.svg`)
-2. Verify file size < 50KB (warn if larger)
-3. If `dark_mode: both`, generate and save dark variant
+2. Verify SVG file size < 50KB (warn if larger)
+3. **MANDATORY: Convert SVG to JPG**:
+   ```bash
+   # Convert SVG to JPG at 1280x640, quality 90
+   convert .github/social-preview.svg -resize 1280x640! -quality 90 -background white -flatten .github/social-preview.jpg
+   ```
+4. Verify JPG meets requirements:
+   - Dimensions: 1280x640
+   - File size: < 1MB (compress if needed)
+5. If `dark_mode: both`, generate dark variant SVG and JPG:
+   - `.github/social-preview-dark.svg`
+   - `.github/social-preview-dark.jpg`
+
+**Note**: The JPG is the file to upload to GitHub's social preview setting. The SVG is kept as an editable source.
 
 ---
 
@@ -286,21 +302,26 @@ Negative prompt: text, watermarks, realistic photos, cluttered, busy patterns
 
 ### Step 5: Verify Output
 
-**For SVG output**:
+**For SVG output** (always accompanied by JPG):
 1. Verify valid XML structure
-2. Check file size < 50KB (warn if 50-100KB, error if >100KB)
+2. Check SVG file size < 50KB (warn if 50-100KB, error if >100KB)
 3. Verify viewBox is 1280x640
+4. **Verify JPG was created**:
+   - File exists at `.github/social-preview.jpg`
+   - Dimensions are exactly 1280x640
+   - File size is under 1MB
+   - If exceeds 1MB, recompress with lower quality
 
-**For image output (PNG/JPG)**:
+**For AI-generated image output (PNG/JPG from DALL-E/Gemini)**:
 1. Verify file exists at output path
-2. Check dimensions meet requirements (≥640x320)
+2. Check dimensions meet requirements (≥640x320, recommended 1280x640)
 3. Check file size is under 1MB
 4. If exceeds 1MB, compress progressively
 
 **Report success with**:
-- File location
-- File size
-- Dimensions
+- SVG file location and size
+- **JPG file location and size** (for GitHub upload)
+- Dimensions (1280x640)
 - Provider used
 
 ### Step 6: Upload to Repository (Optional)
@@ -311,34 +332,45 @@ If `upload_to_repo: true` is configured (or `--upload` flag provided):
    - Parse `git remote get-url origin` to extract owner and repo name
    - Determine current branch with `git branch --show-current`
 
-2. **Prepare upload**:
-   - Read the generated file
+2. **Prepare upload** (upload BOTH files):
+   - Read the SVG source file and JPG output file
    - Encode content as base64 for GitHub API
 
-3. **Check for existing file**:
-   - Use GitHub API to check if output file exists
-   - If exists, retrieve the SHA for update operation
+3. **Check for existing files**:
+   - Use GitHub API to check if files exist
+   - If exist, retrieve the SHA for update operation
 
-4. **Upload via GitHub MCP tool**:
-   Use `mcp__github__create_or_update_file` with:
+4. **Upload via GitHub MCP tool** (both SVG and JPG):
    ```yaml
+   # Upload JPG (for GitHub social preview)
    owner: [detected owner]
    repo: [detected repo]
-   path: [output_path]
-   content: [base64 encoded content]
+   path: .github/social-preview.jpg
+   content: [base64 encoded JPG]
    message: "chore: update social preview image"
    branch: [current or default branch]
    sha: [existing file SHA if updating]
    ```
+   ```yaml
+   # Upload SVG (editable source)
+   owner: [detected owner]
+   repo: [detected repo]
+   path: .github/social-preview.svg
+   content: [base64 encoded SVG]
+   message: "chore: update social preview source SVG"
+   branch: [current or default branch]
+   sha: [existing file SHA if updating]
+   ```
 
 5. **Report upload status**:
-   - Confirm successful upload with commit URL
+   - Confirm successful upload with commit URLs
+   - **Remind user**: The JPG file is what should be selected in GitHub settings
    - Provide GitHub settings link for activating the social preview
 
 **Note**: To set as actual social preview, users must:
 1. Go to repository Settings → General
 2. Scroll to "Social preview"
-3. Click "Edit" and select the uploaded image
+3. Click "Edit" and select the **JPG** image (`.github/social-preview.jpg`)
 
 ## Color Palettes by Domain
 

skills/social-preview/examples/config-svg.md

@@ -2,6 +2,8 @@
 
 Example configuration for using SVG generation, the default and recommended provider.
 
+**Note**: SVG generation ALWAYS produces both `.svg` (editable source) and `.jpg` (for GitHub upload).
+
 ## Configuration
 
 ```yaml
@@ -54,8 +56,10 @@ dark_mode: both
 ```
 
 This creates:
-- `.github/social-preview.svg` (light)
-- `.github/social-preview-dark.svg` (dark)
+- `.github/social-preview.svg` (light SVG)
+- `.github/social-preview.jpg` (light JPG - for GitHub upload)
+- `.github/social-preview-dark.svg` (dark SVG)
+- `.github/social-preview-dark.jpg` (dark JPG)
 
 ## Expected Behavior
 
@@ -65,19 +69,27 @@ When running `/social-preview`:
 2. Domain is detected (DevTools, AI, Web, etc.)
 3. Appropriate color palette is selected
 4. SVG is generated using domain template
-5. File is saved to output path
-6. File location and size are reported
+5. SVG is saved to `.github/social-preview.svg`
+6. **JPG is generated** from SVG (1280x640, quality 90)
+7. JPG is saved to `.github/social-preview.jpg`
+8. Both file locations and sizes are reported
+
+**Output Files**:
+- `.github/social-preview.svg` - Editable source (10-50KB)
+- `.github/social-preview.jpg` - For GitHub upload (<1MB)
 
 ## Benefits of SVG
 
 | Feature | Value |
 |---------|-------|
 | Cost | Free |
 | Speed | Instant |
-| File Size | 10-50KB |
-| Editability | Full (text-based) |
+| SVG File Size | 10-50KB |
+| JPG File Size | 50-200KB |
+| Editability | Full (SVG is text-based) |
 | Consistency | 100% predictable |
 | Dark Mode | Easy variants |
+| GitHub Compatible | JPG always generated |
 
 ## Domain Color Palettes