imgx-mcp 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.9.1 (2026-03-02)
+
+### Added
+
+- **Skill included in npm package** — `skills/image-generation/SKILL.md` and `references/providers.md` now ship with the npm package, making it easier to install the Claude Code skill
+
+### Changed
+
+- README restructured: Skill section moved after Quick Start, Plugin section moved to bottom
+- Skill install instructions added (npm copy, curl from GitHub, manual placement)
+- SKILL.md: added missing MCP parameters (`output_format`, `output_dir`, `model`, `provider` on edit tools)
+- SKILL.md: CLI fallback updated from plugin path to `npx imgx-mcp`
+- providers.md: OpenAI `OUTPUT_FORMAT` corrected from CLI-only to MCP `output_format` parameter
+- npm keywords: added `skill`, `claude-code`
+
 ## 0.9.0 (2026-02-28)
 
 ### Changed

package/README.md

@@ -1,216 +1,133 @@
 # imgx-mcp
 
-AI image generation and editing for Claude Code, Codex CLI, and MCP-compatible AI agents. Provider-agnostic design with capability-based abstraction.
+AI image generation and editing MCP server. Works with Claude Code, Gemini CLI, Cursor, Windsurf, and any MCP-compatible tool.
 
-## Install
+Generate images from text, edit existing images with text instructions, iterate on results — all from your AI coding environment.
 
-### As a Claude Code plugin
+## Quick start
 
-```
-/plugin marketplace add somacoffeekyoto/imgx-mcp
-/plugin install imgx-mcp@somacoffeekyoto-imgx-mcp
-```
-
-After installation, restart Claude Code. The `image-generation` skill becomes available — Claude Code can generate and edit images via natural language instructions.
-
-### Update
-
-#### Claude Code plugin
-
-You can try updating via the plugin manager:
+Add to your tool's MCP config (`.mcp.json`, `settings.json`, etc.):
 
-```
-/plugin update → select "installed" → imgx-mcp → update
+```json
+{
+  "mcpServers": {
+    "imgx": {
+      "command": "npx",
+      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
+      "env": { "GEMINI_API_KEY": "your-key" }
+    }
+  }
+}
 ```
 
-If the update shows no changes or the plugin doesn't reflect the latest version, uninstall and reinstall:
+That's it. Your AI agent can now generate and edit images.
 
-```
-/plugin uninstall imgx-mcp@somacoffeekyoto-imgx-mcp
-/plugin install imgx-mcp@somacoffeekyoto-imgx-mcp
-```
+> **Windows**: Replace `"command": "npx"` with `"command": "cmd"` and prepend `"/c"` to the args array.
 
-Then restart Claude Code.
+## Skill (Claude Code)
 
-#### Standalone CLI
+For Claude Code users, imgx-mcp includes an `image-generation` skill — a guided prompt that teaches Claude how to use the MCP tools effectively. With the skill installed, type `/image-generation` to start a guided workflow.
 
-```bash
-npm update -g imgx-mcp
-```
+### Install the skill
 
-### As a standalone CLI
+Copy the skill directory from the npm package or GitHub repository to your project:
 
 ```bash
-npm install -g imgx-mcp
-```
-
-Requires Node.js 18+.
-
-## Setup
-
-Set up at least one provider:
-
-**Gemini** — get a key from [Google AI Studio](https://aistudio.google.com/apikey) (free tier available):
+# From npm (after npx has cached the package)
+cp -r $(npm root -g)/imgx-mcp/skills .claude/skills
 
-```bash
-imgx config set api-key YOUR_GEMINI_API_KEY --provider gemini
+# Or from the GitHub repository
+curl -sL https://raw.githubusercontent.com/somacoffeekyoto/imgx-mcp/main/skills/image-generation/SKILL.md \
+  -o .claude/skills/image-generation/SKILL.md --create-dirs
+curl -sL https://raw.githubusercontent.com/somacoffeekyoto/imgx-mcp/main/skills/image-generation/references/providers.md \
+  -o .claude/skills/image-generation/references/providers.md --create-dirs
 ```
 
-**OpenAI** — get a key from [OpenAI Platform](https://platform.openai.com/api-keys):
+Or place skill files manually:
 
-```bash
-imgx config set api-key YOUR_OPENAI_API_KEY --provider openai
 ```
-
-Keys are stored in `~/.config/imgx/config.json` (Linux/macOS) or `%APPDATA%\imgx\config.json` (Windows). Alternatively, set environment variables:
-
-```bash
-export GEMINI_API_KEY="your-api-key"
-export OPENAI_API_KEY="your-api-key"
+your-project/
+  .mcp.json                              ← MCP server config (Quick start above)
+  .claude/
+    skills/
+      image-generation/
+        SKILL.md                         ← skill prompt
+        references/
+          providers.md                   ← provider reference
 ```
 
-Environment variables take precedence over the config file.
-
-## Usage
-
-### Generate an image from text
-
-```bash
-imgx generate -p "A coffee cup on a wooden table, morning light" -o output.png
-```
+The skill files are included in the [npm package](https://www.npmjs.com/package/imgx-mcp) under `skills/` and in the [GitHub repository](https://github.com/somacoffeekyoto/imgx-mcp/tree/main/skills/image-generation).
 
-### Edit an existing image
+> **Personal skill** (all projects): Place in `~/.claude/skills/image-generation/` instead of `.claude/skills/`.
 
-```bash
-imgx edit -i photo.png -p "Change the background to sunset" -o edited.png
-```
+### What the skill does
 
-### Iterative editing with `--last`
+The skill guides Claude Code through image workflows: blog covers, iterative editing, provider comparison, icon generation. It knows the MCP tool parameters and best practices, so you get better results with less effort.
 
-```bash
-imgx edit -i photo.png -p "Make the background darker"
-# → {"success": true, "filePaths": ["./imgx-a1b2c3d4.png"]}
+### MCP server vs Skill
 
-imgx edit --last -p "Add warm lighting"
-# Uses the previous output as input automatically
+| | MCP server | Skill |
+|---|---|---|
+| What it does | Exposes image tools to AI agents | Guided prompt for using the tools |
+| Works with | Any MCP-compatible tool | Claude Code |
+| Install | Add to `.mcp.json` | Copy skill files to project |
+| Team sharing | Commit `.mcp.json` to repo | Commit `.claude/skills/` to repo |
 
-imgx edit --last -p "Crop to 16:9" -o final.png
-```
+**Recommended**: Set up the MCP server (Quick start) + install the skill if you use Claude Code.
 
-### Options
+## MCP tools
 
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--prompt` | `-p` | Image description or edit instruction (required) |
-| `--output` | `-o` | Output file path (auto-generated if omitted) |
-| `--input` | `-i` | Input image to edit (`edit` command only) |
-| `--last` | `-l` | Use last output as input (`edit` command only) |
-| `--aspect-ratio` | `-a` | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2` |
-| `--resolution` | `-r` | `1K`, `2K`, `4K` |
-| `--count` | `-n` | Number of images to generate |
-| `--format` | `-f` | Output format: `png`, `jpeg`, `webp` (OpenAI only) |
-| `--model` | `-m` | Model name |
-| `--provider` | | Provider name (default: `gemini`) |
-| `--output-dir` | `-d` | Output directory |
-
-### Configuration
+| Tool | Description |
+|------|-------------|
+| `generate_image` | Generate an image from a text prompt |
+| `edit_image` | Edit an existing image with text instructions |
+| `edit_last` | Edit the last generated/edited image (no input path needed) |
+| `list_providers` | List available providers and capabilities |
 
-```bash
-imgx config set api-key <key> --provider gemini   # Save Gemini API key
-imgx config set api-key <key> --provider openai   # Save OpenAI API key
-imgx config set model <name>      # Set default model
-imgx config set output-dir <dir>  # Set default output directory
-imgx config set aspect-ratio 16:9 # Set default aspect ratio
-imgx config set resolution 2K     # Set default resolution
-imgx config list                  # Show all settings
-imgx config get api-key           # Show a specific setting (API key is masked)
-imgx config path                  # Show config file location
-```
+Images are saved to `~/Pictures/imgx/` by default. File paths are returned in the response. Inline image preview is included in MCP responses (base64).
 
-### Project config (`.imgxrc`)
+### Iterative editing
 
-Generate a template with `imgx init`:
+The `edit_last` tool uses the output of the previous `generate_image` or `edit_image` call as input. This enables a conversational workflow:
 
-```bash
-imgx init
-# → creates .imgxrc in current directory
 ```
-
-Or create manually. Place a `.imgxrc` file in your project directory to set project-level defaults:
-
-```json
-{
-  "defaults": {
-    "model": "gemini-2.5-flash-image",
-    "outputDir": "./assets/images",
-    "aspectRatio": "16:9"
-  }
-}
+"Generate a coffee shop interior" → generate_image
+"Make the lighting warmer"        → edit_last
+"Add a person reading a book"     → edit_last
 ```
 
-Project config is shared via Git. Do not put API keys in `.imgxrc` — use `imgx config set api-key` or environment variables instead.
-
-### Settings resolution
+No need to specify file paths between steps.
 
-Settings are resolved in this order (first match wins):
+## API key setup
 
-1. CLI flags (`--model`, `--output-dir`, etc.)
-2. Environment variables (`IMGX_MODEL`, `IMGX_OUTPUT_DIR`, etc.)
-3. Project config (`.imgxrc` in current directory)
-4. User config (`~/.config/imgx/config.json` or `%APPDATA%\imgx\config.json`)
-5. Provider defaults
+Set up at least one provider:
 
-### Other commands
+**Gemini** — get a key from [Google AI Studio](https://aistudio.google.com/apikey) (free tier available):
 
 ```bash
-imgx providers      # List available providers and their capabilities
-imgx capabilities   # Show detailed capabilities of current provider
+imgx config set api-key YOUR_GEMINI_API_KEY --provider gemini
 ```
 
-### Environment variables
-
-Environment variables override config file settings.
-
-| Variable | Description |
-|----------|-------------|
-| `GEMINI_API_KEY` | Gemini API key |
-| `OPENAI_API_KEY` | OpenAI API key |
-| `IMGX_PROVIDER` | Default provider |
-| `IMGX_MODEL` | Default model |
-| `IMGX_OUTPUT_DIR` | Default output directory |
-
-## Output
-
-All commands output JSON:
-
-```json
-{"success": true, "filePaths": ["./output.png"]}
-```
+**OpenAI** — get a key from [OpenAI Platform](https://platform.openai.com/api-keys):
 
-```json
-{"success": false, "error": "error message"}
+```bash
+imgx config set api-key YOUR_OPENAI_API_KEY --provider openai
 ```
 
-This makes imgx suitable for scripting, CI pipelines, and integration with other tools.
-
-## MCP server
-
-imgx includes an MCP (Model Context Protocol) server, making it available to any MCP-compatible AI coding tool.
+Keys are stored in `~/.config/imgx/config.json` (Linux/macOS) or `%APPDATA%\imgx\config.json` (Windows). Alternatively, pass keys via the `env` section in your MCP config, or set environment variables:
 
-### Exposed tools
+```bash
+export GEMINI_API_KEY="your-api-key"
+export OPENAI_API_KEY="your-api-key"
+```
 
-| Tool | Description |
-|------|-------------|
-| `generate_image` | Generate an image from a text prompt |
-| `edit_image` | Edit an existing image with text instructions |
-| `edit_last` | Edit the last generated/edited image (no input path needed) |
-| `list_providers` | List available providers and capabilities |
+Only include the API keys for providers you want to use. At least one is required.
 
-### Configuration
+## MCP configuration by tool
 
-Add to your tool's MCP config. The `env` section is optional if you have already run `imgx config set api-key`.
+### Claude Code
 
-**Claude Code** (`.mcp.json` / `claude mcp add`):
+`.mcp.json` in your project root:
 
 ```json
 {
@@ -224,11 +141,9 @@ Add to your tool's MCP config. The `env` section is optional if you have already
 }
 ```
 
-On Windows, replace `"command": "npx"` with `"command": "cmd"` and prepend `"/c"` to the args array.
+### Gemini CLI
 
-Or install as a [Claude Code plugin](#install) for automatic MCP registration.
-
-**Gemini CLI** (`~/.gemini/settings.json`):
+`~/.gemini/settings.json`:
 
 ```json
 {
@@ -242,7 +157,9 @@ Or install as a [Claude Code plugin](#install) for automatic MCP registration.
 }
 ```
 
-**Claude Desktop** (`claude_desktop_config.json`):
+### Claude Desktop
+
+`claude_desktop_config.json`:
 
 macOS / Linux:
 
@@ -274,9 +191,11 @@ Windows:
 
 Config file location: `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS). After editing, restart Claude Desktop.
 
-> **Note:** Claude Desktop runs the MCP server from its own app directory. Images will be saved there by default. To control the output location, add `"IMGX_OUTPUT_DIR": "C:\\Users\\you\\Pictures"` to the `env` section, or run `imgx config set output-dir <path>` beforehand.
+> **Note:** Claude Desktop runs the MCP server from its own app directory. To control image output location, add `"IMGX_OUTPUT_DIR": "C:\\Users\\you\\Pictures"` to the `env` section, or run `imgx config set output-dir <path>` beforehand.
 
-**Codex CLI** (`.codex/config.toml`):
+### Codex CLI
+
+`.codex/config.toml`:
 
 ```toml
 [mcp_servers.imgx]
@@ -285,27 +204,34 @@ args = ["--package=imgx-mcp", "-y", "imgx-mcp"]
 env = { GEMINI_API_KEY = "your-key", OPENAI_API_KEY = "your-key" }
 ```
 
+### Other tools
+
 The same `npx` pattern works with Cursor, Windsurf, Continue.dev, Cline, Zed, and other MCP-compatible tools. On Windows, use `cmd /c npx` instead of `npx` directly.
 
-Only include the API keys for providers you want to use. At least one is required.
+## Providers
+
+| Provider | Models | Capabilities |
+|----------|--------|-------------|
+| Gemini | `gemini-3-pro-image-preview`, `gemini-2.5-flash-image` | Generate, edit, aspect ratio, resolution, reference images, person control |
+| OpenAI | `gpt-image-1` | Generate, edit, aspect ratio, multi-output, output format (PNG/JPEG/WebP) |
 
 ## Architecture
 
 imgx separates **model-independent** and **model-dependent** concerns:
 
 ```
-CLI (argument parsing, output formatting)    MCP server (tool definitions, stdio transport)
- ↓                                            ↓
+MCP server (tool definitions, stdio transport)    CLI (argument parsing, output formatting)
+ ↓                                                 ↓
 Core (Capability enum, ImageProvider interface, provider registry, file I/O)
  ↓
 Provider (model-specific API calls, capability declarations)
 ```
 
-CLI and MCP server are two entry points into the same core. Both call the same provider functions.
+MCP server and CLI are two entry points into the same core. Both call the same provider functions.
 
-Each provider declares its supported capabilities. The CLI dynamically enables or disables options based on what the active provider supports. Adding a new provider means implementing the `ImageProvider` interface and registering it — no changes to the CLI layer.
+Each provider declares its supported capabilities. Adding a new provider means implementing the `ImageProvider` interface and registering it — no changes to the MCP or CLI layer.
 
-### Supported capabilities
+### Capability system
 
 | Capability | Description |
 |------------|-------------|
@@ -318,12 +244,118 @@ Each provider declares its supported capabilities. The CLI dynamically enables o
 | `PERSON_CONTROL` | Control person generation in output |
 | `OUTPUT_FORMAT` | Choose output format (PNG, JPEG, WebP) |
 
-### Current providers
+## CLI
 
-| Provider | Models | Capabilities |
-|----------|--------|-------------|
-| Gemini | `gemini-3-pro-image-preview`, `gemini-2.5-flash-image` | All 7 base capabilities |
-| OpenAI | `gpt-image-1` | Generate, edit, aspect ratio, multi-output, output format |
+imgx-mcp also works as a standalone command-line tool.
+
+### Install
+
+```bash
+npm install -g imgx-mcp
+```
+
+Requires Node.js 18+.
+
+### Usage
+
+```bash
+# Generate
+imgx generate -p "A coffee cup on a wooden table, morning light" -o output.png
+
+# Edit
+imgx edit -i photo.png -p "Change the background to sunset" -o edited.png
+
+# Iterative editing
+imgx edit -i photo.png -p "Make the background darker"
+imgx edit --last -p "Add warm lighting"
+imgx edit --last -p "Crop to 16:9" -o final.png
+
+# Provider management
+imgx providers          # List providers and capabilities
+imgx capabilities       # Detailed capabilities of current provider
+```
+
+### CLI options
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--prompt` | `-p` | Image description or edit instruction (required) |
+| `--output` | `-o` | Output file path (auto-generated if omitted) |
+| `--input` | `-i` | Input image to edit (`edit` command only) |
+| `--last` | `-l` | Use last output as input (`edit` command only) |
+| `--aspect-ratio` | `-a` | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2` |
+| `--resolution` | `-r` | `1K`, `2K`, `4K` |
+| `--count` | `-n` | Number of images to generate |
+| `--format` | `-f` | Output format: `png`, `jpeg`, `webp` (OpenAI only) |
+| `--model` | `-m` | Model name |
+| `--provider` | | Provider name (default: `gemini`) |
+| `--output-dir` | `-d` | Output directory |
+
+### Configuration
+
+```bash
+imgx config set api-key <key> --provider gemini   # Save Gemini API key
+imgx config set api-key <key> --provider openai   # Save OpenAI API key
+imgx config set model <name>      # Set default model
+imgx config set output-dir <dir>  # Set default output directory
+imgx config set aspect-ratio 16:9 # Set default aspect ratio
+imgx config set resolution 2K     # Set default resolution
+imgx config list                  # Show all settings
+imgx config get api-key           # Show a specific setting (API key is masked)
+imgx config path                  # Show config file location
+```
+
+### Project config (`.imgxrc`)
+
+Generate a template with `imgx init`:
+
+```bash
+imgx init
+# → creates .imgxrc in current directory
+```
+
+Or create manually:
+
+```json
+{
+  "defaults": {
+    "model": "gemini-2.5-flash-image",
+    "outputDir": "./assets/images",
+    "aspectRatio": "16:9"
+  }
+}
+```
+
+Project config is shared via Git. Do not put API keys in `.imgxrc`.
+
+### Settings resolution
+
+1. CLI flags (`--model`, `--output-dir`, etc.)
+2. Environment variables (`IMGX_MODEL`, `IMGX_OUTPUT_DIR`, etc.)
+3. Project config (`.imgxrc` in current directory)
+4. User config (`~/.config/imgx/config.json` or `%APPDATA%\imgx\config.json`)
+5. Provider defaults
+
+### Output format
+
+All CLI commands output JSON:
+
+```json
+{"success": true, "filePaths": ["./output.png"]}
+```
+
+## Claude Code plugin
+
+The plugin bundles MCP server + skill in one step. If you prefer not to configure `.mcp.json` and skill files manually:
+
+```
+/plugin marketplace add somacoffeekyoto/imgx-mcp
+/plugin install imgx-mcp@somacoffeekyoto-imgx-mcp
+```
+
+Update: `/plugin` → installed → imgx-mcp → update. If the update shows no changes, uninstall and reinstall.
+
+Uninstall: `/plugin uninstall imgx-mcp@somacoffeekyoto-imgx-mcp` then `/plugin marketplace remove somacoffeekyoto-imgx-mcp`.
 
 ## Development
 
@@ -336,28 +368,25 @@ npm run bundle    # TypeScript compile + esbuild bundle
 
 The build produces two bundles:
 
-- `dist/cli.bundle.js` — CLI entry point
 - `dist/mcp.bundle.js` — MCP server entry point
+- `dist/cli.bundle.js` — CLI entry point
 
 ## Uninstall
 
-### Claude Code plugin
+### MCP server
 
-```
-/plugin uninstall imgx-mcp@somacoffeekyoto-imgx-mcp
-/plugin marketplace remove somacoffeekyoto-imgx-mcp
-```
+Remove the `imgx` entry from your tool's MCP configuration file.
+
+### Skill
 
-### Standalone CLI
+Delete the `image-generation/` directory from `.claude/skills/` or `~/.claude/skills/`.
+
+### CLI
 
 ```bash
 npm uninstall -g imgx-mcp
 ```
 
-### MCP server
-
-Remove the `imgx` entry from your tool's MCP configuration file.
-
 ### Clean up configuration (optional)
 
 ```bash
@@ -374,6 +403,9 @@ MIT — [SOMA COFFEE KYOTO](https://github.com/somacoffeekyoto)
 
 ## Links
 
+- [Official page](https://somacoffee.net/imgx-mcp/)
 - [GitHub](https://github.com/somacoffeekyoto/imgx-mcp)
+- [npm](https://www.npmjs.com/package/imgx-mcp)
+- [MCP Registry](https://registry.modelcontextprotocol.io)
 - [SOMA COFFEE KYOTO](https://somacoffee.net)
 - [X (@somacoffeekyoto)](https://x.com/somacoffeekyoto)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imgx-mcp",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "mcpName": "io.github.somacoffeekyoto/imgx",
   "description": "AI image generation and editing for Claude Code, Codex CLI, and MCP-compatible AI agents",
   "type": "module",
@@ -19,8 +19,10 @@
     "gemini",
     "openai",
     "ai",
-    "cli",
-    "mcp"
+    "mcp",
+    "skill",
+    "claude-code",
+    "cli"
   ],
   "author": "SOMA COFFEE KYOTO",
   "license": "MIT",
@@ -28,13 +30,14 @@
     "type": "git",
     "url": "git+https://github.com/somacoffeekyoto/imgx-mcp.git"
   },
-  "homepage": "https://github.com/somacoffeekyoto/imgx-mcp",
+  "homepage": "https://somacoffee.net/imgx-mcp/",
   "bugs": {
     "url": "https://github.com/somacoffeekyoto/imgx-mcp/issues"
   },
   "files": [
     "dist/cli.bundle.js",
     "dist/mcp.bundle.js",
+    "skills/",
     "LICENSE",
     "README.md",
     "CHANGELOG.md"

package/skills/image-generation/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: image-generation
+description: Generate and edit AI images using Gemini or OpenAI. Text-to-image, text-based editing, iterative refinement.
+---
+
+# Image Generation & Editing
+
+Generate and edit images using the imgx MCP tools. Gemini and OpenAI providers supported.
+
+## When to use
+
+- User asks to create, generate, or make an image
+- User asks to edit, modify, or change an existing image
+- User needs a cover image, diagram, icon, or visual asset
+- User wants to refine an image iteratively ("make it darker", "change the background")
+
+## Setup
+
+If the MCP tools (`generate_image`, `edit_image`, `edit_last`, `list_providers`) are already available, skip this section.
+
+### 1. Add MCP server
+
+Add imgx-mcp to the project's `.mcp.json` (create the file if it doesn't exist):
+
+```json
+{
+  "mcpServers": {
+    "imgx": {
+      "command": "npx",
+      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
+      "env": { "GEMINI_API_KEY": "your-key" }
+    }
+  }
+}
+```
+
+On Windows, use `"command": "cmd"` and prepend `"/c"` to args:
+```json
+{
+  "mcpServers": {
+    "imgx": {
+      "command": "cmd",
+      "args": ["/c", "npx", "--package=imgx-mcp", "-y", "imgx-mcp"],
+      "env": { "GEMINI_API_KEY": "your-key" }
+    }
+  }
+}
+```
+
+After adding, restart Claude Code for the MCP server to connect.
+
+### 2. API key
+
+Get at least one API key:
+
+- **Gemini** (default, free tier available): [Google AI Studio](https://aistudio.google.com/apikey)
+- **OpenAI**: [OpenAI Platform](https://platform.openai.com/api-keys)
+
+Set the key in the `.mcp.json` env section (above), or via CLI:
+```bash
+npx imgx-mcp config set api-key YOUR_KEY --provider gemini
+```
+
+## MCP tools
+
+Use these tools directly. No Bash needed.
+
+### generate_image
+
+Generate an image from a text prompt.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `prompt` | Yes | Image description |
+| `aspect_ratio` | No | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2` |
+| `resolution` | No | `1K`, `2K`, `4K` (Gemini only) |
+| `count` | No | Number of images (OpenAI only) |
+| `output_format` | No | `png`, `jpeg`, `webp` (OpenAI only) |
+| `model` | No | Model name |
+| `provider` | No | `gemini` (default) or `openai` |
+| `output` | No | Output file path |
+| `output_dir` | No | Output directory |
+
+### edit_image
+
+Edit an existing image with text instructions. No mask needed — the model determines what to change from the text.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `input` | Yes | Path to the image to edit |
+| `prompt` | Yes | Edit instruction |
+| `aspect_ratio` | No | Output aspect ratio |
+| `resolution` | No | Output resolution (Gemini only) |
+| `output_format` | No | `png`, `jpeg`, `webp` (OpenAI only) |
+| `model` | No | Model name |
+| `provider` | No | `gemini` (default) or `openai` |
+| `output` | No | Output file path |
+| `output_dir` | No | Output directory |
+
+### edit_last
+
+Edit the last generated or edited image. No input path needed — automatically uses the previous output.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `prompt` | Yes | Edit instruction |
+| `aspect_ratio` | No | Output aspect ratio |
+| `resolution` | No | Output resolution (Gemini only) |
+| `output_format` | No | `png`, `jpeg`, `webp` (OpenAI only) |
+| `model` | No | Model name |
+| `provider` | No | `gemini` (default) or `openai` |
+| `output` | No | Output file path |
+| `output_dir` | No | Output directory |
+
+### list_providers
+
+List available providers and their capabilities. No parameters.
+
+## Practical workflows
+
+### Blog cover image
+
+```
+1. generate_image: prompt="A developer's desk with laptop showing terminal, coffee cup, warm morning light" aspect_ratio="16:9" resolution="2K"
+2. Review the result with the user
+3. edit_last: prompt="Make the color palette warmer" (if user wants changes)
+4. edit_last: prompt="Add subtle vignette effect" (further refinement)
+```
+
+### Iterative refinement
+
+The `edit_last` tool is the key to conversational image editing. Each call takes the previous output as input:
+
+```
+generate_image → edit_last → edit_last → edit_last → done
+```
+
+Tell the user what was generated, ask if they want changes, and use `edit_last` to apply them. This is the most natural workflow.
+
+### Comparing providers
+
+Generate the same prompt with different providers to let the user choose:
+
+```
+1. generate_image: prompt="..." provider="gemini"
+2. generate_image: prompt="..." provider="openai"
+3. Show both results. User picks their preferred version
+4. edit_last to refine the chosen one (note: edit_last uses the most recent output)
+```
+
+### Icon or logo variations
+
+```
+1. generate_image: prompt="Minimalist coffee bean icon, white background" aspect_ratio="1:1" count=3
+   (count works with OpenAI provider only)
+2. For Gemini, generate multiple times with slight prompt variations
+```
+
+## Tips
+
+- **Be specific in prompts**: "A wooden table with a ceramic pour-over dripper, steam rising, soft natural light from left" works better than "coffee scene"
+- **Use edit_last for iteration**: Don't ask the user to specify file paths. Just use `edit_last` after any generation or edit
+- **Check provider capabilities**: Use `list_providers` if unsure what a provider supports
+- **Default output**: Images save to `~/Pictures/imgx/` with auto-generated filenames. Use `output` or `output_dir` to customize
+- **Inline preview**: MCP responses include base64 image data for inline display in supported clients
+
+## CLI fallback
+
+If MCP tools are not available (MCP server not configured), fall back to CLI via Bash:
+
+```bash
+npx imgx-mcp generate -p "prompt" -o output.png
+npx imgx-mcp edit -i input.png -p "edit instruction"
+npx imgx-mcp edit --last -p "refine further"
+```
+
+See [providers reference](references/providers.md) for detailed provider capabilities.

package/skills/image-generation/references/providers.md

@@ -0,0 +1,62 @@
+# Provider Reference
+
+## Gemini (default)
+
+| Item | Value |
+|------|-------|
+| Provider name | `gemini` |
+| Default model | `gemini-3-pro-image-preview` |
+| Alternative model | `gemini-2.5-flash-image` |
+| API key env var | `GEMINI_API_KEY` |
+
+### Model comparison
+
+| Feature | gemini-3-pro-image-preview | gemini-2.5-flash-image |
+|---------|---------------------------|------------------------|
+| Quality | Higher | Good |
+| Speed | Slower | Faster |
+| Cost | ~$0.134/image | Lower |
+| Resolution | 1K, 2K, 4K | 1K, 2K |
+
+### Capabilities
+
+| Capability | MCP parameter | Description |
+|------------|---------------|-------------|
+| TEXT_TO_IMAGE | (default) | Generate from text |
+| IMAGE_EDITING | `input` | Edit with text instructions |
+| ASPECT_RATIO | `aspect_ratio` | 7 ratios: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9` |
+| RESOLUTION_CONTROL | `resolution` | `1K`, `2K`, `4K` |
+| REFERENCE_IMAGES | — | Use reference images (future) |
+| PERSON_CONTROL | — | Control person generation (future) |
+
+## OpenAI
+
+| Item | Value |
+|------|-------|
+| Provider name | `openai` |
+| Default model | `gpt-image-1` |
+| API key env var | `OPENAI_API_KEY` |
+
+### Capabilities
+
+| Capability | MCP parameter | Description |
+|------------|---------------|-------------|
+| TEXT_TO_IMAGE | (default) | Generate from text |
+| IMAGE_EDITING | `input` | Edit with text instructions |
+| ASPECT_RATIO | `aspect_ratio` | 7 ratios: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9` |
+| MULTIPLE_OUTPUTS | `count` | Generate up to 4 images per request |
+| OUTPUT_FORMAT | `output_format` | PNG, JPEG, WebP |
+
+### Provider comparison
+
+| Feature | Gemini | OpenAI |
+|---------|--------|--------|
+| Edit (text-only, no mask) | Yes | Yes |
+| Resolution control | Yes (1K/2K/4K) | No |
+| Multiple outputs | No | Yes (up to 4) |
+| Output format selection | No (PNG only) | Yes (PNG/JPEG/WebP) |
+| Iterative editing (`edit_last`) | Yes | Yes |
+
+## Adding new providers
+
+Providers implement the `ImageProvider` interface and register via the provider registry. Each provider declares its supported capabilities. The MCP server and CLI dynamically enable/disable options based on the active provider's capabilities.