@justin_666/square-couplets-master-skills 1.0.0

package/LICENSE

@@ -0,0 +1,54 @@
+**Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License**
+
+Copyright (c) 2026 Justin
+
+本作品採用**創用 CC 姓名標示-非商業性-相同方式分享 4.0 國際版**授權條款進行授權。
+
+This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
+
+要查看本授權條款的副本，請造訪：
+To view a copy of this license, visit:
+https://creativecommons.org/licenses/by-nc-sa/4.0/
+
+或者寄信至：
+Or send a letter to:
+Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
+
+---
+
+### 個人使用授權 (Personal Use License)
+
+**您可以自由地：**
+You are free to:
+
+* **分享** — 在任何媒介以任何形式複製、發行本作品
+Share — copy and redistribute the material in any medium or format
+* **衍生** — 修改、轉換或依本作品進行創作
+Adapt — remix, transform, and build upon the material
+
+**惟需遵守下列條件：**
+Under the following terms:
+
+* **姓名標示** — 您必須給予適當的署名，並提供本授權條款的連結
+Attribution — You must give appropriate credit and provide a link to the license
+* **非商業性** — 您不得將本作品用於商業目的
+NonCommercial — You may not use the material for commercial purposes
+* **相同方式分享** — 如果您改變、轉變或依據本作品進行創作，您必須採用與原先授權條款相同的授權方式來散布您的貢獻
+ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license
+
+---
+
+### 商業授權 (Commercial License)
+
+如需將本專案用於商業目的，請聯繫作者以取得商業授權：
+For commercial use, please contact the author for a commercial license:
+
+* **GitHub:** https://github.com/poirotw66
+* **Project Issues:** https://github.com/poirotw66/Square_Couplets_Master
+
+---
+
+### 免責聲明 (Disclaimer)
+
+本軟體按「現狀」提供，不提供任何形式的明示或暗示擔保。
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

package/README.md

@@ -0,0 +1,297 @@
+# 春聯斗方大師 (Square Couplets Master)
+
+一個使用 Google Gemini AI 生成傳統春聯斗方藝術作品的應用程式。將您的願望轉化為精美的書法藝術作品。
+
+View your app in AI Studio: https://ai.studio/apps/drive/134htDa_3SXqpM65lyE57_S7pY5DiemK4
+
+## ✨ 功能特色
+
+- 🎨 **AI 生成春聯斗方**：輸入關鍵字，自動生成傳統風格的春聯藝術作品
+- 🖼️ **參考圖片支持**：上傳參考圖片，AI 會參考其風格生成作品
+- 📐 **多種解析度**：支持 1K、2K、4K 解析度輸出
+- 🎭 **雙模型選擇**：Gemini 2.5 Flash（快速）和 Gemini 3 Pro（高品質）
+
+## 🚀 快速開始
+
+### 前置需求
+
+- Node.js (建議使用最新 LTS 版本)
+
+### 安裝步驟
+
+1. **安裝依賴套件：**
+   ```bash
+   npm install
+   ```
+
+2. **設置 API Key：**
+   - 在 [.env.local](.env.local) 文件中設置 `GEMINI_API_KEY` 為您的 Gemini API key
+   - 或者直接在應用程式的設置中輸入 API key
+
+3. **運行應用程式：**
+   ```bash
+   npm run dev
+   ```
+
+4. **打開瀏覽器：**
+   - 訪問 `http://localhost:5173`（或終端顯示的地址）
+
+## 🌐 部署到 GitHub Pages
+
+本專案已配置自動部署到 GitHub Pages。當您推送代碼到 `main` 或 `master` 分支時，GitHub Actions 會自動構建並部署應用程式。
+
+### 部署步驟
+
+1. **啟用 GitHub Pages：**
+   - 前往 GitHub 倉庫的 Settings
+   - 點擊左側的 "Pages"
+   - 在 "Source" 部分選擇 "GitHub Actions"
+
+2. **推送代碼：**
+   ```bash
+   git add .
+   git commit -m "Deploy to GitHub Pages"
+   git push origin main
+   ```
+
+3. **查看部署狀態：**
+   - 前往倉庫的 "Actions" 標籤頁
+   - 查看部署工作流程的執行狀態
+
+4. **訪問部署的應用：**
+   - 部署完成後，應用將在以下地址可用：
+   - `https://[您的用戶名].github.io/Square_Couplets_Master/`
+
+### 手動觸發部署
+
+如果需要手動觸發部署，可以：
+- 前往 "Actions" 標籤頁
+- 選擇 "Deploy to GitHub Pages" 工作流程
+- 點擊 "Run workflow" 按鈕
+
+## 💡 使用建議
+
+### ⭐ 推薦使用 Gemini 3 Pro 模型以獲得最佳體驗
+
+**為什麼選擇 Gemini 3 Pro？**
+
+- ✨ **更高品質**：生成的圖片具有更豐富的細節和更精緻的視覺效果
+- 🎨 **更好的風格理解**：對參考圖片的風格理解更準確，生成的作品更貼近您的期望
+- 📐 **支持高解析度**：支持 2K 和 4K 解析度，適合打印和高品質展示
+- 🎯 **更精確的構圖**：對傳統書法和藝術風格的把握更準確
+
+**模型對比：**
+
+| 特性 | Gemini 2.5 Flash | Gemini 3 Pro |
+|------|-----------------|--------------|
+| 生成速度 | ⚡ 快速 | 🐢 較慢 |
+| 圖片品質 | ✅ 良好 | ⭐ 優秀 |
+| 解析度支持 | 1K 僅 | 1K / 2K / 4K |
+| 風格理解 | ✅ 良好 | ⭐ 優秀 |
+| 推薦用途 | 快速測試、迭代 | 最終作品、打印 |
+
+**注意：** Gemini 3 Pro 需要付費 API Key（已啟用帳單）。如果您的 API Key 未啟用帳單，請使用 Gemini 2.5 Flash 模型。
+
+## 🎨 範例作品對比
+
+以下是使用相同關鍵字「萬馬奔騰」生成的範例作品，展示了兩個模型的差異：
+
+### Gemini 2.5 Flash 生成作品
+
+<div align="center">
+  <img src="images/gemini2-5-萬馬奔騰.png" alt="Gemini 2.5 Flash - 萬馬奔騰" width="512" />
+  <p><em>Gemini 2.5 Flash 生成 - 快速生成，品質良好</em></p>
+</div>
+
+### Gemini 3 Pro 生成作品
+
+<div align="center">
+  <img src="images/gemin3-萬馬奔騰.png" alt="Gemini 3 Pro - 萬馬奔騰" width="512" />
+  <p><em>Gemini 3 Pro 生成 - 更高品質，細節豐富</em></p>
+</div>
+
+### 對比總結
+
+從以上範例可以看出：
+
+- **Gemini 2.5 Flash**：生成速度快，適合快速測試和迭代，圖片品質良好
+- **Gemini 3 Pro**：生成時間較長，但圖片品質明顯提升，細節更豐富，更適合最終作品和打印用途
+
+**建議：** 如果您追求高品質的藝術作品，強烈推薦使用 Gemini 3 Pro 模型。
+
+## 📖 使用說明
+
+1. **輸入關鍵字**：在輸入框中輸入您的願望或祝福語（例如：財富、健康、愛情等）
+2. **（可選）上傳參考圖片**：點擊上傳區域選擇一張圖片作為風格參考
+3. **選擇模型和解析度**：點擊右上角設置圖標，選擇您偏好的模型和輸出解析度
+4. **生成作品**：點擊「Generate」按鈕，等待 AI 生成您的專屬春聯斗方
+5. **下載作品**：生成完成後，點擊「Download Artwork」下載您的作品
+
+## 🛠️ 技術棧
+
+- **前端框架**：React 19 + TypeScript
+- **樣式**：Tailwind CSS
+- **AI 模型**：Google Gemini 2.5 Flash / Gemini 3 Pro
+- **構建工具**：Vite
+
+## 📦 NPM 安裝
+
+本專案的 Claude Agent Skills 已發布到 npm，可以通過以下方式安裝：
+
+### 全域安裝（推薦）
+
+```bash
+npm install -g @justin_666/square-couplets-master-skills
+```
+
+安裝後，您可以在任何地方使用 `doufang-skills` 命令：
+
+```bash
+# 列出所有可用的 skills
+doufang-skills list
+
+# 查看特定 skill 的內容
+doufang-skills show generate-doufang-prompt
+
+# 獲取 skill 文件路徑（用於程序化訪問）
+doufang-skills path generate-doufang-image
+
+# 查看幫助
+doufang-skills help
+```
+
+### 本地安裝
+
+```bash
+npm install @justin_666/square-couplets-master-skills
+```
+
+然後在您的專案中使用：
+
+```javascript
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+// 獲取 skill 文件路徑
+const skillPath = join(require.resolve('@justin_666/square-couplets-master-skills'), '../skills/generate-doufang-prompt/SKILL.md');
+const skillContent = readFileSync(skillPath, 'utf-8');
+```
+<｜tool▁calls▁begin｜><｜tool▁call▁begin｜>
+run_terminal_cmd
+
+### 發布到 npm
+
+如果您想將此包發布到 npm，請參考 [NPM_PUBLISH.md](NPM_PUBLISH.md) 文件。
+
+## 🤖 Claude Agent Skills
+
+本專案包含三個 Claude Agent Skills，可在支援該協定的 AI IDE（如 Cursor）中使用：
+
+### 📝 generate-doufang-prompt
+**功能**：根據關鍵字生成專業的春聯斗方藝術作品提示詞
+
+**使用場景**：
+- 用戶提供關鍵字或願望短語
+- 需要生成傳統中國新年藝術作品提示詞
+- 需要將關鍵字轉換為四字祝福語
+
+**示例**：
+```
+"幫我生成一個關於財富的春聯斗方 prompt"
+"為健康長壽主題創建一個 Doufang prompt"
+```
+
+### 🎨 generate-doufang-image
+**功能**：使用 Google Gemini API 生成實際的春聯斗方藝術作品圖片
+
+**使用場景**：
+- 用戶已有提示詞，想要生成實際圖片
+- 需要測試不同模型或解析度
+- 需要生成帶參考圖片風格的藝術作品
+
+**支持的模型**：
+- Gemini 2.5 Flash：快速生成，1K 解析度
+- Gemini 3 Pro：高品質，支持 1K/2K/4K 解析度
+
+**示例**：
+```
+"用 Gemini 3 Pro 生成 2K 解析度的圖片"
+"使用這個 prompt 生成圖片，參考圖片風格"
+```
+
+### ✨ optimize-doufang-prompt
+**功能**：優化 Doufang 提示詞，減少過多留白，改善構圖
+
+**使用場景**：
+- 生成的圖片留白過多
+- 需要改善提示詞品質
+- 生成的圖片構圖不佳
+- 需要更緊湊的構圖
+
+**優化重點**：
+- 將「寬留白」改為「最小留白（2-5%）」
+- 確保 Doufang 佔據 85-95% 的畫面空間
+- 強調視覺衝擊力而非安全邊距
+
+**示例**：
+```
+"優化這個 prompt，減少留白"
+"改善構圖，讓 Doufang 佔據更多畫面"
+```
+
+### 📂 Skills 文件結構
+
+```
+skills/
+├── generate-doufang-prompt/
+│   └── SKILL.md
+├── generate-doufang-image/
+│   └── SKILL.md
+└── optimize-doufang-prompt/
+    └── SKILL.md
+```
+
+### 🚀 如何使用
+
+在 Cursor 或其他支援 Claude Agent Skills 的 IDE 中：
+
+1. **自動載入**：當您提到相關任務時，對應的 skill 會自動載入
+2. **手動調用**：直接使用 skill 名稱來調用特定功能
+3. **組合使用**：可以將多個 skills 組合使用，例如先生成 prompt，再優化，最後生成圖片
+
+**注意**：使用 `generate-doufang-image` skill 時，需要配置 Gemini API Key。
+
+## 📝 授權 (License)
+
+本專案採用 **Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License** (CC BY-NC-SA 4.0) 授權。
+
+Copyright (c) 2026 Justin
+
+### 您可以自由地：
+
+- ✅ **分享** — 在任何媒介以任何形式複製、發行本作品
+- ✅ **衍生** — 修改、轉換或依本作品進行創作
+
+### 惟需遵守下列條件：
+
+- 📌 **姓名標示** — 您必須給予適當的署名，並提供本授權條款的連結
+- 📌 **非商業性** — 您不得將本作品用於商業目的
+- 📌 **相同方式分享** — 如果您改變、轉變或依據本作品進行創作，您必須採用與原先授權條款相同的授權方式來散布您的貢獻
+
+### 商業授權
+
+如需將本專案用於商業目的，請聯繫作者以取得商業授權：
+
+- **GitHub:** [@poirotw66](https://github.com/poirotw66)
+- **Project Issues:** [Square_Couplets_Master](https://github.com/poirotw66/Square_Couplets_Master)
+
+### 授權條款詳情
+
+要查看完整的授權條款，請訪問：
+- [Creative Commons BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)
+
+或查看專案根目錄的 [LICENSE](LICENSE) 文件。
+
+---
+
+**免責聲明：** 本軟體按「現狀」提供，不提供任何形式的明示或暗示擔保。

package/bin/doufang-skills.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+
+/**
+ * Doufang Skills CLI Tool
+ * Provides access to Claude Agent Skills for generating Chinese New Year Doufang artwork
+ */
+
+import { fileURLToPath } from 'url';
+import { dirname, join, resolve } from 'path';
+import { readFileSync, readdirSync, statSync } from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Get package root directory (parent of bin/)
+const packageRoot = resolve(__dirname, '..');
+
+/**
+ * Get the path to skills directory
+ */
+function getSkillsPath() {
+  // Try multiple possible locations
+  const possiblePaths = [
+    join(packageRoot, 'skills'),
+    join(packageRoot, 'node_modules', '@square-couplets-master', 'skills', 'skills'),
+    join(process.cwd(), 'node_modules', '@square-couplets-master', 'skills', 'skills'),
+  ];
+
+  for (const path of possiblePaths) {
+    try {
+      if (statSync(path).isDirectory()) {
+        return path;
+      }
+    } catch (e) {
+      // Path doesn't exist, try next
+    }
+  }
+
+  // Fallback to package root skills
+  return join(packageRoot, 'skills');
+}
+
+/**
+ * List all available skills
+ */
+function listSkills() {
+  const skillsPath = getSkillsPath();
+  
+  try {
+    const skills = readdirSync(skillsPath, { withFileTypes: true })
+      .filter(dirent => dirent.isDirectory())
+      .map(dirent => dirent.name);
+
+    if (skills.length === 0) {
+      console.error('No skills found in', skillsPath);
+      process.exit(1);
+    }
+
+    console.log('\n📚 Available Doufang Skills:\n');
+    
+    for (const skillName of skills) {
+      const skillPath = join(skillsPath, skillName, 'SKILL.md');
+      try {
+        const skillContent = readFileSync(skillPath, 'utf-8');
+        const frontmatterMatch = skillContent.match(/^---\n([\s\S]*?)\n---/);
+        
+        if (frontmatterMatch) {
+          const frontmatter = frontmatterMatch[1];
+          const nameMatch = frontmatter.match(/name:\s*(.+)/);
+          const descMatch = frontmatter.match(/description:\s*(.+)/);
+          
+          const name = nameMatch ? nameMatch[1].trim() : skillName;
+          const desc = descMatch ? descMatch[1].trim() : 'No description';
+          
+          console.log(`  ✨ ${name}`);
+          console.log(`     ${desc}\n`);
+        } else {
+          console.log(`  ✨ ${skillName}\n`);
+        }
+      } catch (e) {
+        console.log(`  ✨ ${skillName} (error reading skill file)\n`);
+      }
+    }
+  } catch (error) {
+    console.error('Error reading skills directory:', error.message);
+    process.exit(1);
+  }
+}
+
+/**
+ * Show a specific skill
+ */
+function showSkill(skillName) {
+  const skillsPath = getSkillsPath();
+  const skillPath = join(skillsPath, skillName, 'SKILL.md');
+  
+  try {
+    const skillContent = readFileSync(skillPath, 'utf-8');
+    console.log(skillContent);
+  } catch (error) {
+    console.error(`Error reading skill "${skillName}":`, error.message);
+    console.error(`\nAvailable skills:`);
+    listSkills();
+    process.exit(1);
+  }
+}
+
+/**
+ * Get skill path (for programmatic access)
+ */
+function getSkillPath(skillName) {
+  const skillsPath = getSkillsPath();
+  return join(skillsPath, skillName, 'SKILL.md');
+}
+
+/**
+ * Main CLI handler
+ */
+function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (!command || command === 'list' || command === 'ls') {
+    listSkills();
+  } else if (command === 'show' || command === 'view') {
+    const skillName = args[1];
+    if (!skillName) {
+      console.error('Usage: doufang-skills show <skill-name>');
+      console.error('\nAvailable skills:');
+      listSkills();
+      process.exit(1);
+    }
+    showSkill(skillName);
+  } else if (command === 'path') {
+    const skillName = args[1];
+    if (!skillName) {
+      console.error('Usage: doufang-skills path <skill-name>');
+      process.exit(1);
+    }
+    const path = getSkillPath(skillName);
+    console.log(path);
+  } else if (command === 'help' || command === '--help' || command === '-h') {
+    console.log(`
+Doufang Skills CLI Tool
+
+Usage:
+  doufang-skills [command] [options]
+
+Commands:
+  list, ls              List all available skills
+  show <skill-name>     Show a specific skill's content
+  path <skill-name>     Get the file path to a skill
+  help                  Show this help message
+
+Examples:
+  doufang-skills list
+  doufang-skills show generate-doufang-prompt
+  doufang-skills path generate-doufang-image
+
+For more information, visit:
+  https://github.com/poirotw66/Square_Couplets_Master
+    `);
+  } else {
+    console.error(`Unknown command: ${command}`);
+    console.error('Run "doufang-skills help" for usage information.');
+    process.exit(1);
+  }
+}
+
+// Run CLI
+main();

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@justin_666/square-couplets-master-skills",
+  "version": "1.0.0",
+  "description": "Claude Agent Skills for generating Chinese New Year Doufang (diamond-shaped couplet) artwork using Google Gemini AI",
+  "type": "module",
+  "main": "bin/doufang-skills.js",
+  "bin": {
+    "doufang-skills": "bin/doufang-skills.js"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "prepublishOnly": "node -e \"require('fs').chmodSync('bin/doufang-skills.js', 0o755)\""
+  },
+  "keywords": [
+    "claude",
+    "agent",
+    "skills",
+    "chinese",
+    "calligraphy",
+    "gemini",
+    "ai",
+    "art",
+    "doufang",
+    "chinese-new-year",
+    "couplet",
+    "traditional",
+    "artwork"
+  ],
+  "author": "Justin",
+  "license": "CC-BY-NC-SA-4.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/poirotw66/Square_Couplets_Master.git"
+  },
+  "bugs": {
+    "url": "https://github.com/poirotw66/Square_Couplets_Master/issues"
+  },
+  "homepage": "https://github.com/poirotw66/Square_Couplets_Master#readme",
+  "files": [
+    "bin/",
+    "skills/",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@google/genai": "^1.37.0",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.0",
+    "@vitejs/plugin-react": "^5.0.0",
+    "dotenv": "^17.2.3",
+    "tsx": "^4.21.0",
+    "typescript": "~5.8.2",
+    "vite": "^6.2.0"
+  }
+}

package/skills/generate-doufang-image/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: generate-doufang-image
+description: Generate Doufang artwork images using Google Gemini API. Use when user wants to create actual artwork images from prompts. Supports both Gemini 2.5 Flash and Gemini 3 Pro models with different resolutions.
+---
+
+# generate-doufang-image Skill
+
+## Instructions
+
+When user wants to generate an actual Doufang artwork image:
+
+1. **Check for API key:**
+   - First, check for `GEMINI_API_KEY` in environment variables
+   - If not found, check for `API_KEY` environment variable
+   - If still not found, prompt user to provide API key or configure it in settings
+
+2. **Select appropriate model:**
+   - **Gemini 2.5 Flash** (`gemini-2.5-flash-image`):
+     - Fast generation
+     - 1K resolution only (1024×1024)
+     - Good for quick iterations and testing
+     - Free-friendly (works with free API keys)
+   - **Gemini 3 Pro** (`gemini-3-pro-image-preview`):
+     - Higher quality with richer details
+     - Supports 1K, 2K, and 4K resolutions
+     - Better style understanding
+     - Requires paid API key (billing enabled)
+
+3. **Handle reference image (if provided):**
+   - If user provides a reference image, include it in the generation
+   - Process the image: compress if needed, convert to base64
+   - Pass reference image to both prompt generation and image generation steps
+   - Ensure the generated prompt incorporates the reference image's style
+
+4. **Generate image using the prompt:**
+   - Use the image prompt from `generate-doufang-prompt` skill or user-provided prompt
+   - If reference image provided, enhance the prompt with style guidance
+   - Handle errors gracefully with user-friendly messages
+   - Retry on transient errors (500, 503, network errors)
+
+5. **Return the result:**
+   - Return base64 encoded image data URL
+   - Or save to file if user requests file output
+   - Provide download link or file path
+
+## Parameters
+
+- `prompt` (required): The image generation prompt (from `generate-doufang-prompt` or user-provided)
+- `model` (optional): 
+  - `"gemini-2.5-flash-image"` (default, fast, 1K only)
+  - `"gemini-3-pro-image-preview"` (high quality, supports 1K/2K/4K)
+- `imageSize` (optional): 
+  - `"1K"` (1024×1024, default, works with both models)
+  - `"2K"` (2048×2048, Pro model only)
+  - `"4K"` (4096×4096, Pro model only)
+- `apiKey` (optional): Gemini API key (if not in environment)
+- `referenceImage` (optional): Base64 encoded reference image or image file path
+
+## Model Selection Guidelines
+
+**Use Gemini 2.5 Flash when:**
+- User wants fast generation
+- User has free API key
+- User is testing or iterating
+- 1K resolution is sufficient
+
+**Use Gemini 3 Pro when:**
+- User wants highest quality
+- User needs 2K or 4K resolution
+- User wants better style understanding
+- User has paid API key with billing enabled
+- User wants final artwork for printing
+
+## Examples
+
+### Example 1: Basic Generation with Flash Model
+
+**Input:**
+```json
+{
+  "prompt": "A diamond-shaped Chinese New Year Doufang couplet on antique gold-flecked red Xuan paper...",
+  "model": "gemini-2.5-flash-image",
+  "imageSize": "1K",
+  "apiKey": "user-api-key"
+}
+```
+
+**Output:**
+- Base64 encoded image data URL: `data:image/png;base64,...`
+- Or file saved to: `./output/doufang-招財進寶.png`
+
+### Example 2: High-Quality Generation with Pro Model
+
+**Input:**
+```json
+{
+  "prompt": "A diamond-shaped Chinese New Year Doufang couplet...",
+  "model": "gemini-3-pro-image-preview",
+  "imageSize": "2K",
+  "apiKey": "user-api-key"
+}
+```
+
+**Output:**
+- Base64 encoded 2K resolution image
+- Higher quality with more details
+
+### Example 3: With Reference Image
+
+**Input:**
+```json
+{
+  "prompt": "A diamond-shaped Chinese New Year Doufang...",
+  "model": "gemini-3-pro-image-preview",
+  "imageSize": "2K",
+  "referenceImage": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
+  "apiKey": "user-api-key"
+}
+```
+
+**Output:**
+- Image generated with reference style incorporated
+- Style elements from reference image preserved
+
+## Error Handling
+
+### Missing API Key
+```
+Error: API Key is missing. Please configure your Gemini API Key in settings or provide it as a parameter.
+```
+
+### Invalid Model/Size Combination
+```
+Error: Flash model only supports 1K resolution. Please use Pro model for 2K/4K or switch to 1K.
+```
+
+### Billing Required (Pro Model)
+```
+Error: Pro model requires paid API Key (billing enabled). Please switch to Flash model or enable billing for your API key.
+```
+
+### Rate Limit
+```
+Error: Rate limit exceeded. Please wait a moment and try again.
+```
+
+### Network Error
+```
+Error: Network connection error. Please check your internet connection and try again.
+```
+
+## Implementation Notes
+
+- Use retry mechanism for transient errors (500, 503, network errors)
+- Compress reference images if they exceed 500KB
+- Validate image formats (JPEG, PNG supported)
+- Handle cancellation signals for long-running requests
+- Provide progress updates for image generation
+
+## When to Use
+
+- User wants to generate actual artwork image
+- User has a prompt ready and wants to see the result
+- User wants to test different models or resolutions
+- User wants to generate artwork with reference image style
+
+## When NOT to Use
+
+- User only wants to generate a prompt (use `generate-doufang-prompt` instead)
+- User wants to optimize an existing prompt (use `optimize-doufang-prompt` instead)
+- User doesn't have API key configured

package/skills/generate-doufang-prompt/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: generate-doufang-prompt
+description: Generate professional Chinese New Year Doufang (diamond-shaped couplet) artwork prompts based on keywords. Use when user wants to create traditional Chinese calligraphy artwork prompts.
+---
+
+# generate-doufang-prompt Skill
+
+## Instructions
+
+When user provides a keyword or wish phrase, generate a professional Doufang artwork prompt using the following process:
+
+1. **Understand the keyword meaning:**
+   - Wealth -> 招財進寶, 富貴吉祥
+   - Health -> 龍馬精神, 延年益壽
+   - Career/Success -> 大展宏圖, 步步高升
+   - Peace/Harmony -> 平安喜樂, 歲歲平安
+   - Love -> 永結同心, 花好月圓
+   - Study/Wisdom -> 學業有成, 金榜題名
+   - General Luck -> 萬事如意, 心想事成
+
+2. **Generate a 4-character blessing phrase** that is:
+   - Elegant and culturally appropriate
+   - Common in Chinese New Year usage
+   - If user input is already a suitable 4-character phrase, use it directly
+   - Otherwise, transform or upgrade it into a proper 4-character blessing phrase
+
+3. **Create detailed image generation prompt** with the following elements:
+   - **Format**: Diamond-shaped (rotated square) Doufang
+   - **Background**: Antique gold-flecked red Xuan paper
+   - **Central theme**: Bold, powerful, energetic traditional Chinese ink wash calligraphy of the 4-character blessing phrase
+   - **Decorative elements**: Symbolic elements that visually represent the keyword (e.g., horse, dragon, pine tree, crane, gold ingots, clouds, mountains, sun, plum blossoms)
+   - **Style**: Traditional Chinese ink painting mixed with realistic illustration, elegant, prestigious, festive but high-class
+   - **Composition**: 
+     - Doufang fills 85-95% of the frame
+     - Centered with minimal elegant margins (2-5% of frame width, just enough to prevent edge cropping)
+     - Fully visible inside the frame, not touching edges
+   - **Quality**: Ultra high detail, 8k, masterpiece, professional artwork, 1:1 aspect ratio
+   - **Lighting**: Soft studio lighting, gentle glow on gold details, museum-quality artwork
+   - **Text requirements**: Clear, correct, readable Chinese characters with no typos or deformed text
+
+4. **Output format:**
+   ```json
+   {
+     "blessingPhrase": "四字祝福語",
+     "imagePrompt": "詳細的英文圖片生成提示詞"
+   }
+   ```
+
+## Examples
+
+### Example 1: Wealth Theme
+
+**Input:** "財富" or "wealth"
+
+**Output:**
+```json
+{
+  "blessingPhrase": "招財進寶",
+  "imagePrompt": "A diamond-shaped Chinese New Year Doufang couplet on antique gold-flecked red Xuan paper. Central theme: bold, powerful, energetic traditional Chinese ink wash calligraphy of the characters '招財進寶'. Around the calligraphy: symbolic elements that visually represent wealth - gold ingots, coins, treasure chests, and prosperity symbols, painted in traditional Chinese ink painting style. Style: traditional Chinese ink painting mixed with realistic illustration, elegant, prestigious, festive but high-class, not cartoon. Material & texture: real Xuan paper texture, gold flecks, red rice paper, visible paper fibers, natural ink diffusion, subtle embossed gold foil details. Color theme: deep Chinese red, gold, black ink, warm highlights. Lighting: soft studio lighting, gentle glow on gold details, museum-quality artwork. Composition: The diamond-shaped Doufang fills 85-95% of the 1:1 frame, centered with minimal elegant margins (approximately 2-5% of frame width, just enough to prevent edge cropping). The entire artwork is fully visible inside the frame, not touching any edge, not cropped, not cut off. Clean background, symmetrical, perfectly framed, suitable for printing and hanging on wall. Quality: ultra high detail, 8k, masterpiece, professional artwork, 1:1 aspect ratio."
+}
+```
+
+### Example 2: Health Theme
+
+**Input:** "健康長壽" or "health longevity"
+
+**Output:**
+```json
+{
+  "blessingPhrase": "延年益壽",
+  "imagePrompt": "A diamond-shaped Chinese New Year Doufang couplet on antique gold-flecked red Xuan paper. Central theme: bold, powerful, energetic traditional Chinese ink wash calligraphy of the characters '延年益壽'. Around the calligraphy: symbolic elements that visually represent health and longevity - pine trees, cranes, peaches, and bamboo, painted in traditional Chinese ink painting style. Style: traditional Chinese ink painting mixed with realistic illustration, elegant, prestigious, festive but high-class, not cartoon. Material & texture: real Xuan paper texture, gold flecks, red rice paper, visible paper fibers, natural ink diffusion, subtle embossed gold foil details. Color theme: deep Chinese red, gold, black ink, warm highlights. Lighting: soft studio lighting, gentle glow on gold details, museum-quality artwork. Composition: The diamond-shaped Doufang fills 85-95% of the 1:1 frame, centered with minimal elegant margins (approximately 2-5% of frame width, just enough to prevent edge cropping). The entire artwork is fully visible inside the frame, not touching any edge, not cropped, not cut off. Clean background, symmetrical, perfectly framed, suitable for printing and hanging on wall. Quality: ultra high detail, 8k, masterpiece, professional artwork, 1:1 aspect ratio."
+}
+```
+
+### Example 3: Direct 4-Character Input
+
+**Input:** "萬馬奔騰"
+
+**Output:**
+```json
+{
+  "blessingPhrase": "萬馬奔騰",
+  "imagePrompt": "A diamond-shaped Chinese New Year Doufang couplet on antique gold-flecked red Xuan paper. Central theme: bold, powerful, energetic traditional Chinese ink wash calligraphy of the characters '萬馬奔騰'. Around the calligraphy: symbolic elements that visually represent energy and vitality - galloping horses, flowing clouds, dynamic movement, painted in traditional Chinese ink painting style. Style: traditional Chinese ink painting mixed with realistic illustration, elegant, prestigious, festive but high-class, not cartoon. Material & texture: real Xuan paper texture, gold flecks, red rice paper, visible paper fibers, natural ink diffusion, subtle embossed gold foil details. Color theme: deep Chinese red, gold, black ink, warm highlights. Lighting: soft studio lighting, gentle glow on gold details, museum-quality artwork. Composition: The diamond-shaped Doufang fills 85-95% of the 1:1 frame, centered with minimal elegant margins (approximately 2-5% of frame width, just enough to prevent edge cropping). The entire artwork is fully visible inside the frame, not touching any edge, not cropped, not cut off. Clean background, symmetrical, perfectly framed, suitable for printing and hanging on wall. Quality: ultra high detail, 8k, masterpiece, professional artwork, 1:1 aspect ratio."
+}
+```
+
+## Key Requirements
+
+- The Doufang should fill **85-95% of the frame** (not less)
+- Minimal margins: **2-5% of frame width** (just enough to prevent edge cropping)
+- **No excessive white space** or wide margins
+- Traditional Chinese artistic style (ink wash, calligraphy)
+- High-quality, printable artwork suitable for hanging
+- Clear, correct Chinese characters with no errors
+- No modern elements, no western style, no watermarks
+
+## When to Use
+
+- User asks to generate a Doufang prompt
+- User provides a keyword or wish phrase
+- User wants to create traditional Chinese New Year artwork
+- User needs a prompt for image generation
+
+## When NOT to Use
+
+- User already has a complete prompt
+- User wants to modify an existing prompt (use `optimize-doufang-prompt` instead)
+- User wants to generate the actual image (use `generate-doufang-image` instead)

package/skills/optimize-doufang-prompt/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: optimize-doufang-prompt
+description: Optimize Doufang prompts to reduce excessive white margins and improve composition. Use when generated images have too much white space, poor framing, or when user wants to improve prompt quality.
+---
+
+# optimize-doufang-prompt Skill
+
+## Instructions
+
+When user reports that generated images have excessive white margins, poor composition, or wants to improve prompt quality:
+
+1. **Identify margin-related issues:**
+   - Look for phrases like "wide margins", "generous margins", "wide white margins", "blank margins"
+   - Check for margin percentages > 5%
+   - Look for "generous blank margins around all four corners"
+   - Identify any instructions that might cause excessive white space
+
+2. **Optimize the prompt by replacing problematic phrases:**
+   
+   **Remove/Replace:**
+   - ❌ "with wide white margins"
+   - ❌ "with generous blank margins"
+   - ❌ "with wide safe margins"
+   - ❌ "generous blank margins around all four corners"
+   - ❌ "wide safe margins around the artwork"
+   
+   **Replace with:**
+   - ✅ "centered with minimal elegant margins (approximately 2-5% of frame width, just enough to prevent edge cropping)"
+   - ✅ "minimal margins - the Doufang should fill most of the frame (85-95% of image area)"
+   - ✅ "The Doufang should occupy 85-95% of the image area, maximizing visual impact"
+
+3. **Add explicit composition instructions:**
+   - Add: "The Doufang should fill 85-95% of the frame"
+   - Add: "Minimal margins (2-5% of frame width)"
+   - Add: "Maximize visual impact by making the Doufang occupy most of the frame"
+   - Add: "Avoid excessive white space or wide margins"
+
+4. **Update framing requirements:**
+   - Ensure instructions specify: "just enough to prevent edge cropping"
+   - Emphasize: "maximizing visual impact"
+   - Remove any mention of "wide" or "generous" margins
+
+## Optimization Rules
+
+### Rule 1: Margin Specification
+**Before:**
+```
+"...with wide white margins around all four corners..."
+```
+
+**After:**
+```
+"...centered with minimal elegant margins (approximately 2-5% of frame width, just enough to prevent edge cropping)..."
+```
+
+### Rule 2: Frame Fill Percentage
+**Before:**
+```
+"...with generous blank margins..."
+```
+
+**After:**
+```
+"...The Doufang should occupy 85-95% of the image area, maximizing visual impact..."
+```
+
+### Rule 3: Composition Emphasis
+**Before:**
+```
+"...wide safe margins around the artwork..."
+```
+
+**After:**
+```
+"...minimal margins - the Doufang should fill most of the frame (85-95% of image area)..."
+```
+
+## Examples
+
+### Example 1: Fixing Wide Margins
+
+**Input Prompt (Problematic):**
+```
+A diamond-shaped Chinese New Year Doufang centered in a 1:1 frame with wide white margins. The artwork is a masterpiece of traditional ink-wash fusion...
+```
+
+**Optimized Prompt:**
+```
+A diamond-shaped Chinese New Year Doufang fills the majority of the 1:1 frame, centered with minimal elegant margins (approximately 2-5% of frame width, just enough to prevent edge cropping). The Doufang should occupy 85-95% of the image area, maximizing visual impact. The artwork is a masterpiece of traditional ink-wash fusion...
+```
+
+### Example 2: Improving Composition Instructions
+
+**Input Prompt (Problematic):**
+```
+Composition: The diamond-shaped Doufang is fully visible and centered, with generous blank margins around all four corners. Clear safe area padding around the diamond shape for printing.
+```
+
+**Optimized Prompt:**
+```
+Composition: The diamond-shaped Doufang fills 85-95% of the 1:1 frame, centered with minimal elegant margins (approximately 2-5% of frame width, just enough to prevent edge cropping). The entire artwork is fully visible inside the frame, not touching any edge, not cropped, not cut off. The Doufang should occupy most of the image area, maximizing visual impact. Clean background, symmetrical, perfectly framed, suitable for printing and hanging on wall.
+```
+
+### Example 3: Complete Prompt Optimization
+
+**Input Prompt (Problematic):**
+```
+Framing requirements:
+- The entire diamond-shaped Doufang must be fully visible inside the image.
+- Wide safe margins around the artwork.
+- No cropping, no touching edges, no cut-off.
+```
+
+**Optimized Prompt:**
+```
+Framing requirements:
+- The entire diamond-shaped Doufang must be fully visible inside the image.
+- Minimal margins - the Doufang should fill most of the frame (85-95% of image area).
+- No cropping, no touching edges, no cut-off.
+- Maximize visual impact by making the Doufang occupy most of the frame.
+```
+
+## Key Optimization Principles
+
+1. **Never use "wide" or "generous" margins** - Always specify minimal margins (2-5%)
+2. **Always specify frame fill percentage** - 85-95% of image area
+3. **Emphasize visual impact** - Over safety margins
+4. **Be specific about margin size** - "2-5% of frame width"
+5. **Clarify purpose** - "just enough to prevent edge cropping"
+
+## When to Use
+
+- User reports images have too much white space
+- User wants to improve prompt quality
+- Generated images have poor composition
+- User wants tighter framing
+- User mentions "too much margin" or "excessive white space"
+
+## When NOT to Use
+
+- User wants to generate a new prompt (use `generate-doufang-prompt` instead)
+- User wants to generate an image (use `generate-doufang-image` instead)
+- Prompt already has optimal composition instructions
+
+## Integration with Other Skills
+
+This skill works best when:
+1. Used after `generate-doufang-prompt` if the generated prompt has margin issues
+2. Used before `generate-doufang-image` to ensure optimal composition
+3. Used to fix prompts that resulted in poor image composition
+
+## Output Format
+
+Return the optimized prompt as a string, maintaining all other aspects of the original prompt while only modifying the composition and margin-related instructions.