@unityclaw/skills 1.0.5 → 1.0.8

package/README.md

@@ -1,6 +1,6 @@
 # @unityclaw/skills
 
-UnityClaw Skills - Claude Code and OpenClaw skill definitions for AI-powered image/video generation, media analysis, and document processing.
+UnityClaw Skills for Claude Code and OpenClaw.
 
 ## Installation
 
@@ -14,20 +14,15 @@ npx @unityclaw/skills --help
 
 ## API Key Configuration
 
-All skills require an API key. You can configure it using the SDK CLI:
+All skills require an API key:
 
 ```bash
-# Install SDK globally
 npm install -g @unityclaw/sdk
-
-# Configure API key (stored in ~/.unityclaw/config.json)
 unityclaw-sdk config set apiKey your-api-key
-
-# Verify configuration
 unityclaw-sdk config
 ```
 
-Or set the environment variable:
+Or:
 
 ```bash
 export UNITYCLAW_API_KEY=your-api-key
@@ -35,105 +30,100 @@ export UNITYCLAW_API_KEY=your-api-key
 
 ## CLI Commands
 
-### Install Skills
-
-Install skills to Claude Code or OpenClaw:
-
 ```bash
 # Install all skills to Claude Code
 npx @unityclaw/skills install
 
 # Install specific skills
-npx @unityclaw/skills install unityclaw-image-generation unityclaw-video-generation-sora
+npx @unityclaw/skills install unityclaw-image-generation unityclaw-video-generation-kling
 
 # Install to OpenClaw
 npx @unityclaw/skills install --target openclaw
-```
-
-### List Available Skills
 
-```bash
+# List available skills
 npx @unityclaw/skills list
-```
 
-### Update Packages
-
-Update SDK and skills to the latest version:
-
-```bash
-# Update local packages
+# Update sdk + skills
 npx @unityclaw/skills update
-
-# Update global packages
-npx @unityclaw/skills update --global
 ```
 
-### Execute Skills Directly
+## Reorganized Skill List
 
-Execute a skill via Claude Code CLI:
+This list is aligned with `~/moox/field-feishu` shortcuts and `server` `ParameterModel` definitions.
 
-```bash
-# Generate an image
-npx @unityclaw/skills /unityclaw-image-generation 我要一张竖屏的桌面背景图
+- Removed from skill list: `sora/*`, `veo/*`
+- No version-level split for same model family (for example, no separate `jimeng-image-v3` skill)
+- Document conversion is abstracted as one skill/API entry instead of many individual shortcut skills
 
-# Analyze a video
-npx @unityclaw/skills /unityclaw-media-analysis https://youtube.com/watch?v=...
-```
+### Image
 
-## Available Skills
+- [unityclaw-image-generation](./unityclaw-image-generation/SKILL.md)
+: Covers `gemini/image/v2` + `jimeng/image` (unified)
+- [unityclaw-image-compress](./unityclaw-image-compress/SKILL.md)
+: Covers `image/compress`
 
-### Image Skills
+### Video
 
-| Skill | Description | Emoji |
-|-------|-------------|-------|
-| [unityclaw-image-generation](./unityclaw-image-generation/SKILL.md) | Generate images using Gemini or JiMeng models | 🎨 |
-| [unityclaw-image-compress](./unityclaw-image-compress/SKILL.md) | Compress images with quality control | 🗜️ |
+- [unityclaw-video-generation-kling](./unityclaw-video-generation-kling/SKILL.md)
+: Covers `kling/video`
+- [unityclaw-video-generation-jimeng-doubao](./unityclaw-video-generation-jimeng-doubao/SKILL.md)
+: Covers `jimeng/video`, `doubao/video`
+- [unityclaw-video-generation-wan-minimax](./unityclaw-video-generation-wan-minimax/SKILL.md)
+: Covers `wan/video`, `minimax/video`
 
-### Video Skills
+### Document
 
-| Skill | Description | Emoji |
-|-------|-------------|-------|
-| [unityclaw-video-generation-sora](./unityclaw-video-generation-sora/SKILL.md) | Generate videos using OpenAI Sora | 🎬 |
-| [unityclaw-video-generation-veo](./unityclaw-video-generation-veo/SKILL.md) | Generate videos using Google Veo | 🎥 |
-| [unityclaw-video-generation-kling](./unityclaw-video-generation-kling/SKILL.md) | Generate videos using Kling AI | 📹 |
-| [unityclaw-video-generation-other](./unityclaw-video-generation-other/SKILL.md) | Generate videos using Doubao, Wan, MiniMax, JiMeng | 🎞️ |
+- [unityclaw-document-translation](./unityclaw-document-translation/SKILL.md)
+: Covers `doc/translate`
+- [unityclaw-document-convert](./unityclaw-document-convert/SKILL.md)
+: Covers generic `doc_convert/image` + `doc_convert/pdf`
 
-### Document Skills
+### Media
 
-| Skill | Description | Emoji |
-|-------|-------------|-------|
-| [unityclaw-document-translation](./unityclaw-document-translation/SKILL.md) | Translate documents between languages | 🌐 |
-| [unityclaw-document-convert](./unityclaw-document-convert/SKILL.md) | Convert document formats (PDF/Word/PPT/Excel/Image) | 📄 |
+- [unityclaw-media-analysis](./unityclaw-media-analysis/SKILL.md)
+: Covers `media_analysis`
+- [unityclaw-media-stats](./unityclaw-media-stats/SKILL.md)
+: Covers `media_stats`
+- [unityclaw-media-user-info](./unityclaw-media-user-info/SKILL.md)
+: Covers `media_user_info`
+- [unityclaw-media-download-xhs](./unityclaw-media-download-xhs/SKILL.md)
+: Covers `xiaohongshu/download`
+- [unityclaw-video-frame-extract](./unityclaw-video-frame-extract/SKILL.md)
+: Covers `video/frame`
 
-### Media Skills
+### IDP
 
-| Skill | Description | Emoji |
-|-------|-------------|-------|
-| [unityclaw-media-analysis](./unityclaw-media-analysis/SKILL.md) | Analyze video/audio content and extract insights | 📊 |
+- [unityclaw-idp-personal-documents](./unityclaw-idp-personal-documents/SKILL.md)
+: Covers `idp/id_card`, `idp/vehicle_license`, `idp/bank_card`
+- [unityclaw-idp-invoice-extraction](./unityclaw-idp-invoice-extraction/SKILL.md)
+: Covers `idp/vat_invoice`, `idp/train_invoice`, `idp/taxi_invoice`
+- [unityclaw-idp-business-extraction](./unityclaw-idp-business-extraction/SKILL.md)
+: Covers `idp/business_license`, `idp/business_card`
+- [unityclaw-idp-contract-extraction](./unityclaw-idp-contract-extraction/SKILL.md)
+: Covers `idp/contract`
 
-## Programmatic Usage
+IDP is intentionally split by scenario (personal/invoice/business/contract), instead of one generic skill, to improve skill routing accuracy and parameter selection success.
 
-```typescript
-import { listSkills, installSkills, executeSkill } from '@unityclaw/skills';
+## Local File Input Support
 
-// List available skills
-const skills = await listSkills();
-console.log(skills);
+With latest SDK, skill examples can use local file paths directly:
 
-// Install skills to Claude Code
-await installSkills('claude', ['unityclaw-image-generation']);
+```ts
+attachment: [{ path: './files/input.pdf' }]
+```
 
-// Install all skills to OpenClaw
-await installSkills('openclaw');
+SDK will auto-upload the local file through `/api/upload` and replace it with a valid `tmp_url`.
 
-// Execute a skill
-await executeSkill('/unityclaw-image-generation A beautiful sunset');
-```
+## Parameter Normalization Notes
 
-## SDK Documentation
+Only endpoints that **require** field-feishu structures are normalized.
 
-- [npm: @unityclaw/sdk](https://www.npmjs.com/package/@unityclaw/sdk)
-- [UnityClaw Homepage](https://unityclaw.com)
+- Text array conversion (`string` -> `[{ type: 'text', text: '...' }]`) is applied only for:
+  `jimeng/image`, `jimeng/image/v3`, `sora/video`, `sora/video/stable`, `veo/video`, `jimeng/video`, `doubao/video`.
+- Label conversion (`'16:9'` -> `{ value: '16:9', label: '16:9' }`) is applied only for endpoints whose `ParameterModel` expects `LabelFieldItem`.
+- For `doubao/video`, duration should use numeric value in `LabelFieldItem.value` when provided (for example `{ value: 5, label: '5' }`).
+- Endpoints that already support plain strings are kept as-is (no forced conversion).
+- If you pass full field-feishu structures, SDK keeps them unchanged.
 
 ## License
 

package/dist/{chunk-VTGLNHDK.js → chunk-CVOSGIUI.js}

@@ -108,7 +108,7 @@ function getClaudeSkillsDir() {
 }
 function getOpenClawSkillsDir() {
   const homeDir = process.env.HOME || process.env.USERPROFILE || "";
-  return process.env.OPENCLAW_SKILLS_DIR || path.join(homeDir, ".openclaw", "skills");
+  return process.env.OPENCLAW_SKILLS_DIR || path.join(homeDir, ".openclaw", "workspace", "skills");
 }
 async function promptForApiKey() {
   const rl = readline.createInterface({

package/dist/cli.cjs

@@ -138,7 +138,7 @@ function getClaudeSkillsDir() {
 }
 function getOpenClawSkillsDir() {
   const homeDir = process.env.HOME || process.env.USERPROFILE || "";
-  return process.env.OPENCLAW_SKILLS_DIR || import_path.default.join(homeDir, ".openclaw", "skills");
+  return process.env.OPENCLAW_SKILLS_DIR || import_path.default.join(homeDir, ".openclaw", "workspace", "skills");
 }
 async function promptForApiKey() {
   const rl = readline.createInterface({

package/dist/cli.js

@@ -3,7 +3,7 @@ import {
   executeSkill,
   installSkills,
   listSkills
-} from "./chunk-VTGLNHDK.js";
+} from "./chunk-CVOSGIUI.js";
 
 // src/cli.ts
 import { program } from "commander";

package/dist/index.cjs

@@ -149,7 +149,7 @@ function getClaudeSkillsDir() {
 }
 function getOpenClawSkillsDir() {
   const homeDir = process.env.HOME || process.env.USERPROFILE || "";
-  return process.env.OPENCLAW_SKILLS_DIR || import_path.default.join(homeDir, ".openclaw", "skills");
+  return process.env.OPENCLAW_SKILLS_DIR || import_path.default.join(homeDir, ".openclaw", "workspace", "skills");
 }
 async function promptForApiKey() {
   const rl = readline.createInterface({

package/dist/index.js

@@ -6,7 +6,7 @@ import {
   installSkills,
   listSkills,
   parseSkill
-} from "./chunk-VTGLNHDK.js";
+} from "./chunk-CVOSGIUI.js";
 export {
   executeSkill,
   getClaudeSkillsDir,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unityclaw/skills",
-  "version": "1.0.5",
+  "version": "1.0.8",
   "description": "UnityClaw Skills - Claude Code and OpenClaw skill definitions for AI-powered image/video generation, media analysis, and more",
   "type": "module",
   "bin": {

package/unityclaw-document-convert/SKILL.md

@@ -22,6 +22,7 @@ metadata:
 # UnityClaw Document Convert
 
 Convert documents between various formats including PDF, Word, PowerPoint, Excel, and images.
+Recommended API is unified `client.document.convertDocument(...)`.
 
 ## Installation
 
@@ -71,11 +72,13 @@ import { UnityClawClient } from '@unityclaw/sdk';
 
 const client = new UnityClawClient();
 
-// Convert PDF to Word
-const result = await client.document.pdf2Word({
+// Convert PDF to Word (unified API)
+const result = await client.document.convertDocument({
   attachment: [
-    { tmp_url: 'https://example.com/document.pdf', name: 'document.pdf' }
-  ]
+    { path: './files/document.pdf' }
+  ],
+  input_format: 'pdf',
+  output_format: 'docx'
 });
 
 // ✅ Correct: Check result.success, access data via result.response.data
@@ -108,6 +111,7 @@ if (result.success && result.response?.data) {
 
 | Method | Description |
 |--------|-------------|
+| `convertDocument()` | Recommended unified conversion API |
 | `convert()` | Generic conversion with format specification |
 
 ## API Reference

package/unityclaw-document-translation/SKILL.md

@@ -73,7 +73,7 @@ const client = new UnityClawClient();
 
 const result = await client.document.translate({
   attachment: [
-    { tmp_url: 'https://example.com/document.pdf', name: 'document.pdf' }
+    { path: './files/document.pdf' }
   ],
   source_language: { value: 'en', label: 'English' },
   target_language: { value: 'zh', label: 'Chinese' }

package/unityclaw-idp-business-extraction/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: unityclaw-idp-business-extraction
+description: Extract fields from business documents (business license, business card)
+version: 1.0.0
+metadata:
+  openclaw:
+    requires:
+      env:
+        - UNITYCLAW_API_KEY
+      bins:
+        - node
+        - npm
+    primaryEnv: UNITYCLAW_API_KEY
+    emoji: "🏢"
+    homepage: https://unityclaw.com
+    install:
+      - kind: node
+        package: "@unityclaw/sdk"
+        bins: []
+---
+
+# UnityClaw IDP - Business Extraction
+
+Use this skill for business document extraction:
+- `business_license`
+- `business_card`
+
+## SDK APIs
+
+```typescript
+await client.idp.businessLicense({ attachments: [{ path: './files/business-license.jpg' }] });
+await client.idp.businessCard({ attachments: [{ path: './files/business-card.jpg' }] });
+```
+
+Or generic API:
+
+```typescript
+await client.idp.extract('business_license', {
+  attachments: [{ path: './files/business-license.jpg' }]
+});
+```
+
+## Input
+
+```typescript
+{
+  attachments: AttachmentInput[]
+}
+```
+
+## Notes
+
+- This skill groups enterprise scenarios to avoid over-generic routing.
+- Output fields vary between license and card extraction.

package/unityclaw-idp-contract-extraction/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: unityclaw-idp-contract-extraction
+description: Extract structured fields from contract files
+version: 1.0.0
+metadata:
+  openclaw:
+    requires:
+      env:
+        - UNITYCLAW_API_KEY
+      bins:
+        - node
+        - npm
+    primaryEnv: UNITYCLAW_API_KEY
+    emoji: "📑"
+    homepage: https://unityclaw.com
+    install:
+      - kind: node
+        package: "@unityclaw/sdk"
+        bins: []
+---
+
+# UnityClaw IDP - Contract Extraction
+
+Use this skill for contract parsing:
+- `contract`
+
+## SDK APIs
+
+```typescript
+await client.idp.contract({
+  attachments: [{ path: './files/contract.pdf' }]
+});
+```
+
+Or generic API:
+
+```typescript
+await client.idp.extract('contract', {
+  attachments: [{ path: './files/contract.pdf' }]
+});
+```
+
+## Input
+
+```typescript
+{
+  attachments: AttachmentInput[]
+}
+```
+
+## Notes
+
+- Preferred for long contract OCR + key field extraction scenarios.
+- Read extracted data from `result.response.data`.

package/unityclaw-idp-invoice-extraction/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: unityclaw-idp-invoice-extraction
+description: Extract fields from invoice and ticket documents (VAT, train, taxi)
+version: 1.0.0
+metadata:
+  openclaw:
+    requires:
+      env:
+        - UNITYCLAW_API_KEY
+      bins:
+        - node
+        - npm
+    primaryEnv: UNITYCLAW_API_KEY
+    emoji: "🧾"
+    homepage: https://unityclaw.com
+    install:
+      - kind: node
+        package: "@unityclaw/sdk"
+        bins: []
+---
+
+# UnityClaw IDP - Invoice Extraction
+
+Use this skill for invoice/ticket extraction:
+- `vat_invoice`
+- `train_invoice`
+- `taxi_invoice`
+
+## SDK APIs
+
+```typescript
+await client.idp.vatInvoice({ attachments: [{ path: './files/vat-invoice.pdf' }] });
+await client.idp.trainInvoice({ attachments: [{ path: './files/train-ticket.jpg' }] });
+await client.idp.taxiInvoice({ attachments: [{ path: './files/taxi-invoice.jpg' }] });
+```
+
+Or generic API:
+
+```typescript
+await client.idp.extract('vat_invoice', {
+  attachments: [{ path: './files/vat-invoice.pdf' }]
+});
+```
+
+## Input
+
+```typescript
+{
+  attachments: AttachmentInput[]
+}
+```
+
+## Notes
+
+- Files can be image/PDF according to each underlying IDP type.
+- Output schema differs by type; parse from `result.response.data`.

package/unityclaw-idp-personal-documents/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: unityclaw-idp-personal-documents
+description: Extract structured fields from personal identity documents (ID card, vehicle license, bank card)
+version: 1.0.0
+metadata:
+  openclaw:
+    requires:
+      env:
+        - UNITYCLAW_API_KEY
+      bins:
+        - node
+        - npm
+    primaryEnv: UNITYCLAW_API_KEY
+    emoji: "🪪"
+    homepage: https://unityclaw.com
+    install:
+      - kind: node
+        package: "@unityclaw/sdk"
+        bins: []
+---
+
+# UnityClaw IDP - Personal Documents
+
+Use this skill for personal document extraction:
+- `id_card`
+- `vehicle_license`
+- `bank_card`
+
+## SDK APIs
+
+```typescript
+await client.idp.idCard({ attachments: [{ path: './files/id-card.jpg' }] });
+await client.idp.vehicleLicense({ attachments: [{ path: './files/vehicle-license.jpg' }] });
+await client.idp.bankCard({ attachments: [{ path: './files/bank-card.jpg' }] });
+```
+
+Or generic API:
+
+```typescript
+await client.idp.extract('id_card', {
+  attachments: [{ path: './files/id-card.jpg' }]
+});
+```
+
+## Input
+
+```typescript
+{
+  attachments: AttachmentInput[]
+}
+```
+
+`AttachmentInput` supports:
+- `tmp_url`
+- local path (`path` / `localPath` / `filePath`), SDK auto-uploads to `/api/upload`
+
+## Notes
+
+- This category is split from invoice/business/contract to improve skill routing success.
+- Output fields vary by type; read from `result.response.data`.

package/unityclaw-image-generation/SKILL.md

@@ -22,6 +22,7 @@ metadata:
 # UnityClaw Image Generation
 
 Generate high-quality images using Gemini or JiMeng (Doubao) AI models.
+This skill keeps JiMeng as one unified entry (no separate v3 skill).
 
 ## Installation
 
@@ -89,6 +90,12 @@ if (result.success && result.response?.data) {
 }
 ```
 
+You can pass local files directly and SDK will auto-upload them:
+
+```typescript
+attachment: [{ path: './files/reference.jpg' }]
+```
+
 ## Available APIs
 
 ### Gemini Image Generation
@@ -117,30 +124,56 @@ const result = await client.image.geminiV2({
 
 ### JiMeng Image Generation
 
+> **IMPORTANT:** JiMeng uses different parameters than Gemini. Pay attention to the `size` and `model_selector` values.
+
 ```typescript
-// Basic usage
+// Basic usage (defaults to Seedream 5.0 Lite model)
 const result = await client.image.jimeng({
   prompt: '一只可爱的猫咪在花园里玩耍',
-  size: { value: '1024x1024', label: '1:1' }
+  size: { value: '2048x2048', label: '2K 1:1' }
 });
 
-// With all options
+// With Seedream 5.0 Lite (supports web_search, 2K and 3K resolutions)
 const result = await client.image.jimeng({
   prompt: 'A serene Japanese garden in autumn',
   attachment: [{ tmp_url: 'https://...', name: 'style.jpg' }],
-  size: { value: '1024x1024', label: '1:1' },
-  model_selector: { value: 'general', label: 'General' },
-  web_search: { value: true, label: 'Enable' },
+  size: { value: '2048x2048', label: '2K 1:1' },
+  model_selector: { value: 'doubao-seedream-5-0-260128', label: 'Seedream 5.0 Lite' },
+  web_search: { value: 'true', label: 'Enable' },
   image_count: { value: 4, label: '4 images' }
 });
 
-// JiMeng V3
-const result = await client.image.jimengV3({
+// With Seedream 4.5 (supports 4K resolution, no web_search)
+const result = await client.image.jimeng({
   prompt: 'A mystical forest with glowing mushrooms',
-  size: { value: '1024x1024', label: '1:1' }
+  size: { value: '4096x4096', label: '4K 1:1' },
+  model_selector: { value: 'doubao-seedream-4-5-251128', label: 'Seedream 4.5' }
 });
+
 ```
 
+#### JiMeng Size Options
+
+| Resolution | 5.0 Lite | 4.5 | Size Values |
+|------------|----------|-----|-------------|
+| 2K | ✅ | ✅ | `2048x2048`, `1728x2304`, `2304x1728`, `2848x1600`, `1600x2848`, `2496x1664`, `1664x2496`, `3136x1344` |
+| 3K | ✅ | ❌ | `3072x3072`, `2592x3456`, `3456x2592`, `4096x2304`, `2304x4096`, `3744x2496`, `2496x3744`, `4704x2016` |
+| 4K | ❌ | ✅ | `4096x4096`, `3520x4704`, `4704x3520`, `5504x3040`, `3040x5504`, `4992x3328`, `3328x4992`, `6240x2656` |
+
+> **Note:** `web_search` only works with Seedream 5.0 Lite model.
+
+## Troubleshooting (`/api/jimeng/image`)
+
+If you see backend errors like `{"code":1254500}`, check these first:
+
+- Do not use `jimeng/image/v3` size values (for example `1152x896`) on `/api/jimeng/image`.
+- For `/api/jimeng/image`, use 2K/3K/4K size values such as:
+  `2048x2048`, `3072x3072`, `4096x4096`.
+- Model and size must match:
+  - `doubao-seedream-5-0-260128` does **not** support 4K.
+  - `doubao-seedream-4-5-251128` does **not** support 3K.
+- `web_search=true` only works with `doubao-seedream-5-0-260128`.
+
 ## Parameter Types
 
 ### GeminiImageParams
@@ -158,11 +191,12 @@ const result = await client.image.jimengV3({
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `prompt` | `string \| TextFieldItem[]` | Yes | Text description (supports Chinese) |
-| `attachment` | `AttachmentFieldItem[]` | No | Reference images |
-| `size` | `LabelFieldItem` | Yes | Size: `'1024x1024'` (1:1), `'896x1152'` (9:16), `'1152x896'` (16:9) |
-| `model_selector` | `LabelFieldItem` | No | Model type |
-| `web_search` | `LabelFieldItem` | No | Enable web search for references |
-| `image_count` | `LabelFieldItem \| number` | No | Number of images to generate |
+| `attachment` | `AttachmentFieldItem[]` | No | Reference images for style transfer |
+| `size` | `LabelFieldItem` | Yes | Size: `'2048x2048'` (2K), `'3072x3072'` (3K), `'4096x4096'` (4K) and more |
+| `model_selector` | `LabelFieldItem` | No | Model: `'doubao-seedream-5-0-260128'` (5.0 Lite) or `'doubao-seedream-4-5-251128'` (4.5) |
+| `web_search` | `LabelFieldItem` | No | Enable web search (5.0 Lite only): `'true'` or `'false'` |
+| `image_count` | `LabelFieldItem \| number` | No | Number of images to generate (0-5) |
+| `model` | `string` | No | Direct model override |
 
 ## Examples
 
@@ -267,4 +301,4 @@ console.log('Task Folder:', result.taskFolder); // e.g., "~/Documents/tasks/2026
 ## Related Skills
 
 - [unityclaw-image-compress](../unityclaw-image-compress/SKILL.md) - Compress generated images
-- [unityclaw-video-generation-sora](../unityclaw-video-generation-sora/SKILL.md) - Generate videos with Sora
+- [unityclaw-video-generation-kling](../unityclaw-video-generation-kling/SKILL.md) - Generate videos